agentproto CLI

The agentproto binary is the reference host for AgentProto agent-CLI adapters. It installs adapter packages (claude-code, hermes, opencode, codex, mastra-agent, openclaw, …), runs them locally for a single turn or a long-lived session, exposes them as a daemon over an outbound WebSocket tunnel, and orchestrates multi-agent swarms through the runtime kernel.

This tree is tool docs — what the binary does, what flags it takes, what files it touches. For the protocol it implements, see the AIPs at https://agentproto.sh/docs.

Status: alpha. The package is pre-1.0 (0.1.0-alpha.x). See ../../VERSIONING.md for what the alpha guarantees and what may change between minor releases.

Three ways in

Pick whichever matches what you're trying to do:

• Run a Claude Code (or other) session locally — getting-started.md walks through install
  • run for a single turn. For a persistent session attached to your terminal, see verbs/sessions.md.
• Share your machine with a hosted agent (a self-hosted gateway, …) — see verbs/auth.md for the device flow, then verbs/serve.md for the daemon with --connect.
• Orchestrate a multi-agent swarm — concepts/swarms.md introduces the model, verbs/run-swarm.md covers the verb.

Reference

Verbs

• agentproto auth — log in to a host (RFC 8628 device flow)
• agentproto browser — manage browser service sessions (Camofox, Bureau, Chromium)
• agentproto chat / chat-tui — interactive REPL on a daemon agent session
• agentproto config — read/write ~/.agentproto/config.json
• agentproto daemon — install/start/stop the background service
• agentproto install — install an adapter or a runtime profile
• agentproto mcp-bridge — stdio MCP proxy to the daemon /mcp endpoint
• agentproto models — list runnable models per adapter with provider-key status
• agentproto plugins — manage runtime plugins
• agentproto run — one-shot adapter turn
• agentproto run-swarm — kernel-routed multi-agent loop
• agentproto serve — daemon mode (local-only or tunnelled)
• agentproto sessions — browse/start/attach/stop daemon sessions
• agentproto setup — re-run an adapter's post-install pipeline
• agentproto tunnel — manage public Cloudflare/Ngrok tunnels
• agentproto workspace — register local workspaces

Concepts

• Adapters — what @agentproto/adapter-* packages are
• Plugins — extending the swarm kernel
• Roles — spawn-time delegation gate, the privilege lattice, and role packs
• Runtime profiles — runtime-profile/<name> scaffolding
• Swarms — manifest + kernel cycle model
• Credentials — how host tokens are stored
• Session transcripts — structured per-session capture, event kinds, native vs daemon export

Guides

• Use agentproto as an MCP server inside coding CLIs — register the daemon in Claude Code, Codex, and Hermes

File reference

• ~/.agentproto/config.json schema
• ~/.agentproto/credentials.json format

Install

npm i -g @agentproto/cli
agentproto --version

Node ≥ 20.9.0. Optional node-pty for terminal sessions — npm i -g node-pty if you want agentproto sessions terminal and PTY-backed agent attach.