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. wharf dsh installs its pinned runtime and bridge automatically; it still requires your own DEEPSEEK_API_KEY.
• Node.js 22 or newer and npm are available so the installer can install the Claude, Codex, and DeepSeek Harness ACP bridges used by AgentWharf.

Install Wharf on macOS or Linux:

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

On Windows, install Node.js 22 or newer first, then run PowerShell as the user who will run Wharf:

irm https://github.com/winghv/agentwharf/releases/latest/download/install.ps1 | iex

The Windows installer downloads the matching .exe release, installs wharf.exe under %USERPROFILE%\.local\bin by default, and installs the .cmd ACP provider bridges. Add that directory to PATH when the installer reports that it is missing. install.sh is a Unix shell script and must not be pasted into CMD or PowerShell; Git Bash detects Windows and prints the PowerShell command.

The installer downloads the matching prebuilt binary from GitHub Releases, installs the wharf command, and installs the Claude/Codex ACP bridge wrappers plus the pinned official DeepSeek Harness runtime in a versioned, isolated prefix under ~/.agentwharf/providers/dsh-runtime-<version>/, and installs a SuperWHV policy patch under ~/.agentwharf/providers/dsh/cordis.yml. The DSH prefix is isolated because its runtime packages exchange identity-sensitive symbols and must not resolve through stale packages from another release line. Set AGENTWHARF_SKIP_DSH=1 only when DSH is intentionally not needed.

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.

Set the DeepSeek credential in the shell that will run Wharf. The API key is used only by the local DSH child process and is never sent to SuperWHV:

$ export DEEPSEEK_API_KEY=your-deepseek-api-key
# optional: export DEEPSEEK_BASE_URL=https://api.deepseek.com
# optional: export DEEPSEEK_MODEL=deepseek-v4-flash

PowerShell:

$env:DEEPSEEK_API_KEY = "your-deepseek-api-key"
# optional: $env:DEEPSEEK_BASE_URL = "https://api.deepseek.com"
# optional: $env:DEEPSEEK_MODEL = "deepseek-v4-flash"

Start the agent you want to use:

$ wharf claude
# or:
$ wharf codex
# or:
$ wharf dsh

wharf dsh uses the installed user-level policy patch with the official DSH ACP profile. No manual DSH bridge installation or system path configuration is required. When this machine is already paired, the command also starts the background dispatch daemon before returning, so Tasks created for DSH in the Agent Workbench are picked up without another local command. It does not start an interactive DSH terminal session or initiate pairing by itself.

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. wharf dsh starts this daemon when the machine is already paired; otherwise start it explicitly:

$ 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