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 both agentwharf and the short wharf onboarding command, and installs the claude-agent-acp / codex-acp provider bridge wrappers.

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.

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
  -> creates a device pairing code
  -> waits for Console confirmation
  -> exchanges the machine token for a session-bound adapter token
  -> starts the provider adapter
  -> connects to the AgentWharf Hub

Tokens are kept in memory. They are not printed by the CLI and are not written to disk.

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:

$ agentwharf serve
$ agentwharf 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:

$ agentwharf 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