Rig Relay

Rig Relay — a governed local server/control-plane with a desktop cockpit.

Rig Relay is a local server/control-plane with a desktop cockpit frontend for coordinating agent work, observing runtime/tool behavior, and producing structured evidence. CLI entry points are debug/admin/operator shims, not the primary product surface. The product provides receipt-backed evidence, worktree isolation, multi-provider consultation (Council), and fleet orchestration. It exposes MCP tools for Antigravity, VS Code, and Zed, and speaks ACP for editor-integrated agent sessions.

Quick Start

git clone https://github.com/juliantorr-es/rig-relay
cd rig-relay
uv sync
uv run rig-relay                # launch desktop cockpit
# or headless: uv run rig-relay --server-only

On first launch, Rig Relay will walk you through provider setup — pick a provider, get an API key, and you're ready. No API key? Rig Relay still starts in dry-run mode with full projection and WebSocket available.

uv tool install git+https://github.com/juliantorr-es/rig-relay.git --force

Release Readiness

To verify RC readiness:

uv run python scripts/rig_release_gate_validate.py
uv run python scripts/rig_rc_golden_path_check.py
uv run python scripts/rig_rc_installability_check.py

See docs/json/release_gate/rc_readiness_gate.v1.json for phase status. See docs/json/release_candidate/rc_reviewer_golden_path.v1.json for the golden path checklist.

Current Path

Rig Relay is a standalone desktop application built with pywebview. The primary surface is a chat-first console with widget panels for workspace state, fleet status, provider health, and Council (multi-provider adversarial review).

uv run rig-relay

Desktop Cockpit

Operator, Review, System, and Technical layout modes. Widgets at three disclosure levels: compact chips, standard cards, and full-page expanded views. Chat sends to AgentLoop → LLM → tools → response. WebSocket streams projections and chat state to the frontend. The server/control-plane can also be launched headlessly for review, browser validation, and live exercise of the cockpit path.

uv run rig-relay --dry-run       # projection dump, no window
uv run rig-relay --server-only   # WebSocket + URL, headless

Protocol Surfaces

Rig Relay exposes four protocol surfaces for different integration patterns:

Surface	Role	Description
ACP Agent	Editor ↔ Agent	Rig presents as a governed coding agent to Zed, JetBrains, VS Code. Sessions, progress events, edit proposals, permission gating.
MCP Client	Rig ↔ External Tools	Rig consumes external MCP servers for additional tools and context.
MCP Server	Host ↔ Rig	Rig exposes governed tools, resources, and prompts to Antigravity, Claude Desktop, Cursor, and other MCP hosts. Tiered: read-only → analysis → validation → patch proposal → mutation.
WebSocket	Cockpit ↔ Backend	Local projection stream for the desktop cockpit. Token-gated, localhost-only, content-light.

See docs/protocol-surfaces.md for details.

Legacy Path

Rig Relay is a derivative of mistralai/mistral-vibe. The vibe command and legacy Textual TUI are retained for compatibility during migration but are not the product identity.

rig-relay legacy          # legacy CLI
rig-relay legacy --agent plan

Legacy config paths (.vibe/, ~/.vibe/) are read as compatibility fallbacks. Set RIG_RELAY_DISABLE_LEGACY_CONFIG=1 to require the new paths.

Agent Profiles

Rig Relay ships with built-in agent profiles. Select with --agent:

Profile	Type	Tools	Use
default	Agent	Standard	Normal development with approval gates
orchestrator	Agent	Git, task dispatch, consult	Fleet orchestration, roadmap planning
plan	Agent	Read-only	Exploration and planning
explorer	Subagent	grep, read_file	Codebase exploration
builder	Subagent	write_file, search_replace, task	Patch application in scratch worktrees
cleaner	Subagent	validate, validation_suite	Post-build validation and cleanup
bug-exterminator	Subagent	cleaner tools + task	Hard merge conflict resolution

Safety Story

Rig Relay communicates bounded autonomy, not vague automation:

Scope	Default	Meaning
Isolated lane execution	Allowed (demo)	Ralph creates worktrees, scoped execution. No mutation of live workspace.
Live runtime mutation	Always blocked	No agent can mutate the live runtime workspace.
Merge	Requires adoption approval	Adoption must pass human approval + SHA match.
Push to preproduction	Requires preproduction approval	Human approval + validation suite must pass.

These gates align with OWASP agent security best practices: least-privilege tools, per-tool permission scoping, separate tool sets by trust level, and explicit authorization for sensitive operations.

Frontend is a dumb renderer. The backend owns all policy transitions. The frontend receives projection fields like isolated_lane_execution_enabled and merge_enabled and displays them as human labels ("Allowed" / "Blocked" / "Requires adoption approval"). The frontend never infers or overrides policy.

Features

• Chat-first console — Operator, Review, System, Technical layout modes with adaptive widget grids
• Council — Multi-provider adversarial review with structured opinions and receipt-backed findings
• Fleet orchestration — Roadmap planning, sprint scoping, mission dispatch to subagents on isolated worktrees
• Receipt-backed evidence — Every tool call, checkpoint, and consultation produces a receipt
• Worktree isolation — Agents operate in git worktrees under .rig/relay/worktrees
• Slash commands — /init, /worktree, /fleet, /council, /orchestrator, /provider, and more
• Provider onboarding — Interactive setup for DeepSeek, OpenAI, Anthropic, Google, Mistral, OpenRouter
• MCP server — 16 governed tools across 5 tiers, exposed for Antigravity/VS Code/Zed
• ACP agent — Editor-integrated session control with progress streaming and permission gating
• Event Fabric — DuckDB read-side analytics over event fabric JSONL, Prometheus metrics, WAL durability
• Mission Topology — Spiderweb visualization in cockpit (compact/standard/expanded), static HTML renderer
• Live Mutation Readiness — 12-gate policy engine with HMAC-SHA256 attestation signing
• Multi-tenant Isolation — TenantRegistry, tenant-scoped event dispatch, scoped permissions
• Fleet Orchestration — Bridge fleet controller, mission topology projection (16 nodes, 10 edges)
• Enterprise Attestation + RBAC — Attestation sign/verify, 5-backend secrets resolution, scoped RBAC

Configuration

Rig Relay looks for configuration at:

1. ./.rig/relay/config.toml (project-specific)
2. ~/.rig/relay/config.toml (user-global)

API keys are stored in ~/.rig/relay/.env. On first launch with no key configured, the onboarding wizard walks through provider selection and key setup.

Development

uv run pytest                  # full suite
uv run pyright                 # type check
uv run ruff check --fix .      # lint
uv run ruff format .           # format

License

AGPL-3.0-or-later. Derivative of mistralai/mistral-vibe. See LICENSE and UPSTREAM.md.

Development Status

Rig Relay is in alpha (v0.1.0a1). The release-candidate gate is HOLD — installability smoke tests pass but dogfood operational readiness is not yet proven.

Dogfood Golden Path

A structured reviewer checklist gates the PROMOTE decision: docs/json/release_candidate/rc_reviewer_golden_path.v1.json

To exercise the golden path:

1. Install: git clone + uv sync
2. Understand the product: read this README and the release gate phases
3. Launch server: uv run rig-relay-acp
4. Launch cockpit: uv run rig-relay
5. Run a real work lane and inspect structured evidence
6. Run the release gate validator: uv run python scripts/rig_release_gate_validate.py

Structured Evidence

All evidence is JSON/JSONL/CSV — no Markdown-as-evidence. Key evidence paths:

• docs/json/release_gate/rc_blockers.v1.jsonl — open RC blockers
• docs/json/release_gate/rc_deferred_risks.v1.jsonl — deferred risks with justifications
• docs/json/release_gate/rc_candidate_verdict.v1.json — current verdict
• .rig/reports/reports.jsonl — append-only structured reports
• ~/.rig/relay/sessions/<id>/observability.jsonl — session telemetry

Telemetry & Privacy

Telemetry is local-first and opt-out only. No raw file contents, secrets, or private code are emitted. All content-derived data uses SHA256 hashes. Telemetry-disabled mode visibly degrades behavior and is covered by release-gate evidence. See docs/governance/usage-data-doctrine.md.