agentwharf

README

AgentWharf

Open-source session gateway for coding agents. AgentWharf lets you run Claude, Codex, Gemini, or another ACP-compatible agent on your own machine, then control the session from SuperWHV Console with durable replay, multi-client fanout, and permission sync.

Links: Website | SuperWHV Console | Protocol spec | TypeScript client

Quickstart: Connect Your Own Machine

Prerequisites:

• Access to SuperWHV Console.
• The agent you want to run is installed and authenticated on this machine.
• npm is available so the installer can install the Claude and Codex ACP bridge wrappers used by wharf claude and wharf codex.

Install Wharf:

$ curl -fsSL https://github.com/winghv/agentwharf/releases/latest/download/install.sh | sh

The script downloads the matching prebuilt binary from GitHub Releases, installs the wharf command, and installs the claude-agent-acp / codex-acp provider bridge wrappers.

Run the same install command again to upgrade. When wharf already exists on PATH, the installer upgrades that existing directory in place so the active command is replaced instead of installing a second copy behind an older binary. It also removes the legacy agentwharf command from that directory. Set AGENTWHARF_INSTALL_DIR only when you explicitly want to override the target directory.

Recent versions also provide the shorter upgrade flow:

$ wharf upgrade --check
$ wharf upgrade

Wharf checks for a newer GitHub release in the background at most once every 24 hours when an agent command starts. The check has a short timeout, never blocks session startup, and only prints an upgrade reminder. Set WHARF_NO_UPDATE_CHECK=1 to disable automatic checks. Upgrades only run after the user explicitly invokes wharf upgrade.

Managed v2 sessions also renew their short-lived adapter authorization before it expires. This keeps a long-running wharf claude process and its existing Workbench session connected without restarting the provider. Temporary Hub, WebSocket, or network interruptions are retried automatically with bounded backoff. Wharf resumes the same Session, keeps the same provider process alive, and safely retries durable events whose acknowledgement was lost. It exits when the user stops it or when the Session authority is explicitly rejected or terminated.

Start the agent you want to use:

$ wharf claude
# or:
$ wharf codex

The CLI prints a pairing prompt:

Pair this machine at https://cloud.superwhv.me/app/machines
device_code: dev_xxxxx
user_code: ABCD-EFGH

Then open Console Machines, paste the device_code and user_code, give the machine a name, and confirm. The session appears in Console and can be reopened from the browser or another client.

After the first successful pairing, Wharf stores a local machine credential in ~/.agentwharf/machine.json with file mode 0600. Later wharf claude or wharf codex runs reuse that machine identity and create a fresh session without showing another pairing code.

To switch accounts or organizations, remove the local pairing and pair again:

$ wharf logout
$ wharf claude --pair

wharf machine unlink is an alias for wharf logout. If the machine is released from Console, the next Wharf run clears the stale local credential and prompts you to pair again.

Auto-Dispatch: Run Tasks From Console Without Touching This Machine

A paired machine can also receive Tasks created in the Console automatically. Start the local dispatch daemon:

$ wharf machine serve

The daemon polls for auto-dispatch claims every 10 seconds (adjustable with --poll-interval, minimum 1 second), refreshes the machine token before it expires, and for each Task it receives: exchanges the claim with the machine identity alone, starts the local provider adapter, waits for the adapter to reach an interactive state, and delivers the first instruction as the session's client. Task creation in the Console then runs end to end with no manual step on the machine.

• --poll-interval SECONDS — polling cadence (default 10, minimum 1).
• --max-concurrent N — how many Tasks the daemon dispatches in parallel (default 2, FIFO order).
• --startup-smoke — exit after the first successful dispatch; used by the platform's release smoke.

The machine credential file must exist (pair once first). In-flight dispatches are persisted under ~/.agentwharf/dispatch/ (mode 0700 directory, 0600 files) so a daemon restart resumes the send with the same deterministic command id — a resend is acknowledged as a duplicate, never delivered twice. The daemon never logs instructions, claim codes, or tokens. Stop the daemon with Ctrl-C; running adapter sessions are terminated with the daemon process.

Why AgentWharf

• Connect your own machine: keep your local provider login, quota, and secrets.
• Durable sessions: Hub-issued seq lets clients reconnect and replay missed events in order.
• Multi-client control: the same agent session can be viewed and controlled from CLI, browser, editor, or phone.
• Permission sync: approval requests are normalized and broadcast through the same session protocol.
• ACP first: providers should connect through Agent Client Protocol; stdio and structured-stream fallbacks are available for advanced adapters.

How It Works

wharf claude / wharf codex
  -> reuses the local machine token, or creates a device pairing code on first use
  -> exchanges the machine token for a session-bound adapter token
  -> starts the provider adapter
  -> connects to the AgentWharf Hub

The machine token is stored locally so the machine can create future sessions. Session-bound adapter tokens stay in memory only and are never printed by the CLI.

Core pieces:

• AgentWharf Hub: the single authority for a session event stream. It assigns seq, persists durable events, fans out live events, and replays gaps.
• Adapter: bridges Claude, Codex, Gemini, or another provider into the AgentWharf session protocol.
• Protocol: versioned WebSocket frames, durable and ephemeral events, commands with idempotency, scopes, and replay semantics.

Advanced: Local Self-Host

Use this path when you want to run a local Hub without SuperWHV Console pairing:

$ wharf serve
$ wharf wrap --agent claude --acp
# open the local URL from a browser or phone to observe and control the session

Advanced and test harnesses can still use the explicit managed pairing form:

$ wharf wrap --agent claude --acp --pair --cloud https://cloud.superwhv.me/v1

Most users should start with wharf claude or wharf codex.

Repository Layout

spec/             # protocol spec (authoritative)
protocol/         # frame and event types, codecs, version negotiation
hub/              # hub library: connections, seq, fanout, replay
store/            # EventStore implementations (SQLite, Postgres)
auth/             # Authenticator implementations
masking/          # streaming secret masking
adapter/          # core adapter, ACP bridge, fallback runners
client-ts/        # TypeScript client SDK
examples/         # minimal web UI
cmd/agentwharf/   # CLI: serve / wrap / claude / codex / gemini

Status

Pre-release. The protocol spec and implementation are under active development; public release follows internal validation. The project is Apache-2.0 licensed.

License

Apache-2.0