agentproto CLI

agentproto is a small command-line binary that runs on your machine and connects to Guilde. It does three jobs:

1. Installs and drives agent CLIs — Claude Code, OpenAI Codex, sst/opencode, Nous Hermes, OpenClaw — all behind one wrapper that speaks ACP (Agent Client Protocol).
2. Hosts a local daemon that an operator dispatched from the Guilde cloud can reach over a secure outbound tunnel. So Guilde never needs SSH or VPN access to your machine — your machine reaches out.
3. Streams sessions back to Guilde so the work an agent CLI does (file edits, shell commands, tool calls) shows up in the same /sessions list as everything else, under the same governance and audit log.

You install it once per machine, sign in once per Guilde account, and after that any operator in any guild you belong to can dispatch a CLI session to your laptop.

Install

npm (any platform)

npm install -g @agentproto/cli

This puts an agentproto binary on your PATH. Verify:

agentproto --version
# agentproto 0.1.0-alpha

Homebrew (macOS / Linux)

brew install agentproto/tap/agentproto

From source (workspace dev)

If you're working inside the agentik-studio monorepo:

cd projects/agentproto/ts/packages/cli
pnpm build
pnpm link --global

The agentproto binary now points at your local build and tracks every rebuild.

Sign in to Guilde

The CLI uses the OAuth 2.0 Device Authorization Grant (RFC 8628) — the same flow Claude Code, gh, and gcloud use. You never copy-paste a token from a dashboard.

agentproto auth login --host https://guilde.work

The CLI:

1. Fetches https://guilde.work/.well-known/agentproto-host.json to discover the OAuth endpoints.
2. Asks Guilde for a one-time device code.
3. Prints a short human code and opens your browser to the approval page.

agentproto auth: open
  https://guilde.work/cli/auth?code=L7Q8XRQ
and enter code  L7Q-8XRQ

agentproto auth: waiting for approval…

In the browser you'll see:

• Which machine is asking (the CLI sends a label — defaults to username@hostname)
• Which scopes it's requesting (tunnel:connect, agent-cli:dispatch, …)
• An Approve or Deny button

Click Approve. The CLI's next poll receives a long-lived bearer token, persists it to ~/.agentproto/credentials.json (mode 0600), and you're signed in.

Local-dev variant

If you're running Guilde locally:

agentproto auth login --host http://localhost:3040
# → opens http://localhost:3041/cli/auth?code=…

The CLI auto-detects http vs https from the scheme; ws:// and wss:// work too.

Anatomy of the credential file

{
  "version": 1,
  "hosts": {
    "https://guilde.work": {
      "token": "apt_…",
      "tokenType": "Bearer",
      "expiresAt": "2027-05-11T08:21:11.000Z",
      "subject": "user_abc123",
      "scope": "tunnel:connect agent-cli:dispatch",
      "obtainedAt": "2026-05-11T08:21:11.000Z",
      "deviceLabel": "jeremy@laptop"
    }
  }
}

One file per user; multiple Guilde hosts (prod, staging, a self-hosted gateway) live side-by-side under their URL keys.

Check status

agentproto auth status

✓ active  https://guilde.work
         subject: user_abc123
         scope:   tunnel:connect agent-cli:dispatch
         label:   jeremy@laptop
         expires in 364d  (obtained 2026-05-11T08:21:11.000Z)

--json for machine-readable output. --host <url> to narrow to a specific host.

Run the local daemon

Once signed in, start the daemon that operators can dispatch to:

agentproto serve --connect wss://guilde.work/agentproto/tunnel
# agentproto serve: using token from credentials.json (expires in 364d)
# agentproto serve: tunnel UP — guild operators can now dispatch to this machine

No --token flag needed; the daemon reads it from ~/.agentproto/credentials.json. Leave the process running (a tmux pane, a launchd job, a systemd unit — your call).

The daemon binds locally on 127.0.0.1:18790 for the HTTP gateway and dials out to Guilde over the WebSocket tunnel. Nothing reaches in — your machine is the initiator on every connection.

Install an agent CLI

The whole point of agentproto is that one operator can run sessions inside many different agent CLIs. Install any of the bundled ones with:

agentproto install claude-code     # Anthropic's Claude Code (via ACP wrapper)
agentproto install codex           # OpenAI Codex (via @zed-industries/codex-acp)
agentproto install opencode        # sst/opencode (first-party ACP)
agentproto install hermes          # Nous Research Hermes
agentproto install openclaw        # OpenClaw — coding-agent platform

For each adapter, install walks four phases:

1. Version check — if the binary already answers in the right range, the install is skipped. "Already installed (version X.Y.Z). Pass --force to reinstall."
2. Install — runs the manifest's install methods in declared order (npm, brew, curl, …) until one succeeds.
3. Setup — for adapters that need post-install configuration (daemon, gateway checks, credentials), agentproto walks a manifest-declared setup[] pipeline. Steps are idempotent — already-completed ones short-circuit without re-prompting.
4. Ready check — a final round-trip to confirm the adapter can answer.

Example for openclaw, which has the heaviest setup:

agentproto install openclaw
agentproto install [1/2] curl https://openclaw.ai/install.sh | bash
…
agentproto: 'openclaw' installed.
agentproto: running setup for 'openclaw'…
[1/2] cmd/install-daemon    Installs and starts the OpenClaw background daemon.
[1/2] $ openclaw onboard --install-daemon
…
[2/2] cmd/ready-check       Confirms the local Gateway is reachable.
[2/2] $ openclaw gateway probe
agentproto: setup for 'openclaw' complete.

Re-run setup standalone any time:

agentproto setup openclaw                    # all pending steps
agentproto setup openclaw --only ready-check # just one
agentproto setup openclaw --force            # ignore the ledger; re-run everything

Sign out / revoke

agentproto auth logout --host https://guilde.work

Calls Guilde's revocation endpoint server-side (so the token row is marked revoked and your daemon's tunnel will close on next handshake), then deletes the local copy. List or revoke other machines' tokens from Settings → Machine Tokens in the Guilde dashboard.

Token lifecycle, at a glance

Troubleshooting

/cli/auth redirects to /login. Your Guilde session expired. Sign in to Guilde first, then click the CLI URL again — the ?code= query param is still in the URL, so approval will pick up where it left off.

agentproto: device code expired before approval. You waited longer than 10 minutes between running auth login and clicking Approve. Re-run auth login for a fresh code.

agentproto serve: ⚠ credentials are expired. Your token's expiresAt has passed. Run auth login again to refresh.

Browser didn't open. Pass --no-browser to suppress the auto-open and copy the URL by hand. (Useful on SSH-attached hosts and CI.)

Behind a corporate proxy. Set HTTPS_PROXY / HTTP_PROXY before invoking auth login and serve; the CLI's fetch honours the standard env vars.

What's next

• Browser sessions — how operators reach sites that need a logged-in cookie jar.
• Secrets — how Guilde stores per-guild credentials (Stripe keys, Anthropic keys, …) that operators consume.
• The Machine Tokens page (Settings → Machine Tokens) is the audit / revoke surface for everything agentproto auth login issues.