relaydeck 0.1.1

Local-first fleet OS for CLI coding agents — harness-native, plugin-extensible.

[!WARNING] Early beta release. relaydeck is brand new and moving fast, so expect rough edges, breaking changes, and the occasional bug. Please open an issue if something breaks, and contributions are always welcome.

relaydeck

Orchestrate agents. Plug the world in.

One local daemon, one dashboard, your entire fleet.
Run CLI coding agents in parallel: live terminals, durable peer-to-peer messaging,
your choice of model providers, and a plugin stack you extend per workspace.
No cloud account. No telemetry.

_HARNESSES

_PROVIDERS

curl -fsSL https://relaydeck.ai/install.sh | sh

or with pip:

pip install relaydeck

then start the daemon (dashboard at http://127.0.0.1:8765):

relaydeck daemon start

---

What it is

relaydeck is a local-first fleet OS for CLI coding agents. It wraps the real vendor CLIs you already use (Claude Code, Codex, Cursor, OpenCode, pi), runs them unattended in PTYs, and gives you one place to watch, message, and automate them. Everything runs on your machine; state lives in ~/.relaydeck and a local SQLite db, and secrets stay in a vault on the daemon host.

Harness-native	Drives real CLI agents, not a replacement model runtime
Local-first	State in ~/.relaydeck + SQLite; secrets in the on-host vault
Fleet-aware	Agents discover peers by purpose/tags; durable peer messaging with late drain
Observable	Live PTY terminals, semantic status, usage metering, SSE; no polling
CLI = API = UI	Every operation works from the shell, the HTTP API, and the dashboard
Plugin-extensible	Harnesses, providers, messaging, skills, automations: all plugins

---

Works with every harness

Each harness maps your agent config (model, autonomy, system prompt) onto the vendor CLI. Install at least one on your $PATH.

Harness	CLI	Agent type	Notes
Claude Code	claude	claude-code	Permission modes, hook integrations
Codex	codex	codex-cli	Sandbox + approval translation
Cursor	cursor-agent	cursor-cli	Subscription auth; per-agent config dir
OpenCode	opencode	opencode-cli	Config-file instruction injection
Antigravity	agy	antigravity	Google-account auth; workspace-trust pre-seed
pi	pi	pi	Reference harness; system-prompt append
relaydeck native	pi	relaydeck	Fleet operator: pi plus extension tools (messaging, agents, dashboard)

---

Bring any provider

Bundled provider plugins for Anthropic, OpenAI, OpenRouter, and Ollama, plus any OpenAI-compatible endpoint (Groq, Together, Fireworks, Cerebras, DeepSeek, xAI, Mistral, vLLM, and more). Keys live in the vault, never in agent configs.

---

The dashboard

The web dashboard at http://127.0.0.1:8765 is the primary UI: a fleet home with live usage and worker pulse, plus a per-agent lens that shows the live PTY terminal, real-time usage and cost tiles, and panels for identity, context, events, config, inbox, and compose. Agents see their peers through an auto identity preamble and message each other durably; incoming messages are pushed straight into the prompt.

---

Quickstart

Requirements: Python 3.12+ and at least one harness CLI on your $PATH.

# Register this project as a workspace with messaging enabled.
relaydeck init . --plugin messaging

# Start the daemon (dashboard at http://127.0.0.1:8765).
relaydeck daemon start

# Create two agents with distinct roles.
relaydeck agent create planner --type claude-code \
  --purpose "Plan changes; do not implement"
relaydeck agent create coder --type codex-cli \
  --purpose "Implement scoped patches from planner specs"
relaydeck agent start planner coder

# Send work; agents discover peers via the identity preamble.
relaydeck workspace message --agent planner \
  "Plan: add --dry-run to relaydeck plugin uninstall. Keep it under 50 LOC."

# Observe
relaydeck view              # built-in TUI
open http://127.0.0.1:8765  # web dashboard (primary UI)

relaydeck --help documents every command. With the daemon running, the OpenAPI docs live at http://127.0.0.1:8765/docs.

---

Extend with plugins

Everything beyond the core runtime is a RelaydeckPlugin: discovered at startup, capability-gated, and removable without forking the engine. A 30-plugin bundle ships in the box.

Plugin	What it adds
vault	Secrets vault with a key-name-only API and CLI management
github	Poll gh for issues/PRs and route them through rules to agents
telegram	Drive an agent from a chat; auto-discover chats into a registry
messaging	Durable agent-to-agent inbox plus dashboard surfaces
prompts	Agents ask questions with tap-able choices, not blocking stdin
hitl	Human-in-the-loop escalation over pluggable channels
metering · usage_limits	Token/cost tiles; rolling session and weekly quotas with auto-pause
skills · theme · dashboard	Agent-authored skills, themes, and dashboard layouts
file_watcher · gateway · loop	Workspace file events, webhooks, scheduled and event-driven agents

relaydeck plugin list
relaydeck plugin new my-plugin          # scaffold: harness | provider | skill
relaydeck plugin dev ./my-plugin        # editable install
relaydeck plugin verify ./my-plugin     # manifest + skill validation

Plugins register CLI commands, HTTP routes, dashboard lenses/tiles, workers, skills, and event subscriptions; capabilities declared in plugin.toml gate SDK access at runtime. See CONTRIBUTING.md for the authoring guide.

---

Core concepts

Concept	Description
Daemon	One per machine: PTYs, workers, FastAPI, SSE, WebSocket terminals
Workspace	Registered project directory; plugins listed in agent.toml
Agent	Named harness instance (~/.relaydeck/agents/<id>.yaml is source of truth)
Message	Durable row in SQLite; injected to the PTY when live, drained on start
Worktree workspace	Parallel git checkout as a first-class workspace (branch per task)
Plugin	CLI + API + UI contributions declared in plugin.toml

                    +---------------------------------------+
  CLI / scripts     |          relaydeck daemon             |     Web dashboard
  relaydeck ... --->|  orchestrator . plugins . event bus   |<---- localhost:8765
       HTTP/SSE     |         |              |              |      (live SSE)
                    |    harness PTYs    SQLite state       |
                    |   claude . codex . agents . msgs      |
                    |   cursor . pi  .   usage . events     |
                    +---------------------------------------+

  ~/.relaydeck/   agents/*.yaml   workspaces/*/agent.toml   vault.yaml   runtime/relaydeck.db

One install ships relaydeck/ (engine + host contract) and plugins/ (every official plugin). Core imports zero plugins; plugin authors import public facades only: relaydeck.sdk, relaydeck.harness, relaydeck.provider, and so on.

---

More

Remote control via Telegram

Route a Telegram chat to an agent and drive the fleet from your phone. Slash commands act on the routed agent without being forwarded into the harness, so they behave uniformly across every harness type:

Command	Effect
/new (/clear, /fresh, /reset)	Start a fresh session (drops the harness resume flag)
/restart	Restart the agent's PTY, keeping its history
/screenshot	Send a snapshot of the agent's live terminal
/stop · /status · /help	Stop, inspect, or list commands

relaydeck telegram setup                  # store the bot token in the vault
relaydeck telegram routes-add \           # map a chat to (workspace, agent)
  --chat <chat-id> --workspace <ws> --agent <agent>

Observe external agent runtimes

relaydeck observes Hermes Agent and OpenClaw runtimes alongside the fleet it manages: health and risk posture only, with no mutation or secret access.

relaydeck external detect ~/.hermes
relaydeck external add ~/.openclaw --probe
relaydeck external list

Development

git clone https://github.com/relaydeck/relaydeck.git && cd relaydeck
uv sync --group dev
uv run pytest -q -m "not e2e"     # fast CI-equivalent suite
uv run relaydeck plugin verify    # all bundled manifests
uv run ruff check relaydeck tests plugins

Resource
Contributing	CONTRIBUTING.md
Testing	TESTING.md
Architecture notes	AGENTS.md
Security	SECURITY.md
Changelog	CHANGELOG.md

---

Acknowledgements

relaydeck is harness-native: it wraps real CLI coding agents rather than shipping its own model runtime. Huge thanks to the pi coding agent (relaydeck's reference harness), and to Claude Code, Codex, Cursor, OpenCode, and Antigravity. We were also inspired by ideas from across the open agent ecosystem, including Nous Research's Hermes Agent and OpenClaw, which relaydeck can observe read-only.

The dashboard builds on Lit, xterm.js, IBM Plex & JetBrains Mono, Heroicons, and Simple Icons. Full attributions live in CREDITS.md. Product names, logos, and trademarks belong to their respective owners.

License

MIT