agentproto CLI

The agentproto binary is the reference host for AgentProto agent-CLI adapters. It installs adapter packages (claude-code, claude-sdk, hermes, opencode, jcode, codex, mastra-agent, openclaw, antigravity, grok-cli, copilot-cli, …), 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.20.0). 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:

Reference

Verbs

  • agentproto agent — create/list AIP-42 agent manifests under .agents/<id>/AGENT.md
  • agentproto app — package, unpack, or serve an agentproto app bundle (.agentapp)
  • agentproto acp — manage generic ACP agents (zero-code ACP CLIs)
  • agentproto adapters — manage runtime adapters (swarm-kernel substrates/dispatchers/executors)
  • agentproto auth — log in to a host (RFC 8628 device flow)
  • agentproto brain — fuzzy (BM25) search over a workspace's ingested session transcripts
  • 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 conversation — locate the native transcript behind a session, or the session behind a native transcript
  • agentproto cron — durable cron jobs on the daemon (command, fresh agent, or re-prompt a live session)
  • agentproto daemon — install/start/restart/stop the background service
  • agentproto devices — list/rename/revoke devices known to this daemon
  • agentproto doctor — read-only health check of the whole install (--json for bug reports)
  • agentproto harness — freshness + safe upgrades of the agent CLI each adapter spawns (outdated / check / upgrade, with rollback)
  • agentproto host — load: why is this machine slow; health: OK/WARN/CRIT verdict on whether it can take more agents
  • agentproto install — install an adapter or a runtime profile
  • agentproto install-mcp — register the daemon's MCP server with installed coding CLIs
  • agentproto mcp-bridge — stdio MCP proxy to the daemon /mcp endpoint
  • agentproto mcp-app — stdio MCP server scoped to one installed app's tools
  • agentproto mcp — imported-MCP maintenance: OAuth login for remote MCPs, move secrets to the keychain, mount imports natively per adapter
  • agentproto models — list runnable models per adapter with provider-key status
  • agentproto onboard — alias of the setup wizard
  • agentproto pack — generate a versioned skill pack from a manifest
  • agentproto pair — end-to-end pairing with a daemon over an untrusted rendezvous
  • agentproto permissions — held tool-permission requests: list, approve/deny, answer harness questions, or auto-resolve with watch rules
  • agentproto policy — CLI surface for the daemon's completion-policy engine (shell/judge gates, commit + human-ack)
  • agentproto review — run, verify and scaffold REVIEW.md reviews (pre-push hook + GitHub Actions shim)
  • agentproto provider-preset — list provider gateway definitions + key-env status
  • agentproto preset — manage saved user spawn configurations
  • agentproto quota — live provider quota for a named auth profile (AIP-67)
  • agentproto accounts — account slots (slot:claude-primary): list them, swap a primary/secondary pair, move alive sessions
  • agentproto remote — publish this gateway (or another local port) to the internet via Cloudflare, bearer-gated
  • agentproto rendezvous — self-host the untrusted pairing broker
  • agentproto run — one-shot adapter turn
  • agentproto run-swarm — kernel-routed multi-agent loop
  • agentproto sandbox — attach to an already-existing sandbox (Box/e2b) without tearing it down
  • agentproto sentinel — watch a GitHub PR/subject, deliver matching events back into a session's inbox
  • agentproto serve — daemon mode (local-only or tunnelled)
  • agentproto sessions — browse/start/attach/stop daemon sessions
  • agentproto setup — onboarding wizard (no slug), or re-run an adapter's post-install pipeline (setup <slug>)
  • agentproto task — create/list/claim/update tasks on the daemon's Task ledger
  • agentproto tunnel — manage public Cloudflare/Ngrok tunnels
  • agentproto usage — local-derived, provider-agnostic spend estimate over a rolling window
  • agentproto workflow — start, inspect, and cancel background workflow runs on the daemon
  • agentproto workspace — register local workspaces; check verifies an AIP-34 workspace/v2 tree
  • agentproto worktree — git worktree lifecycle (provision under worktrees.root, status-aware ls, guarded/salvage removal, gc)
  • agentproto branch — branch gc: classify local/remote/orphan refs as reclaim/review/hold, reversible apply, review queue, operator approve/restore
  • agentproto maintain — plan/review (and optionally apply) branch + worktree + sandbox checkpoint gc for a repo, via the built-in repo-maintenance app's workflow
  • agentproto steward — judge idle agent sessions, then close or flag them with a recorded outcome, via the built-in session-steward app's workflow (dry run by default)

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
  • Device fleet — driving a fleet of paired hosts from one controller: the three capabilities, bring-up, addressing, and the F1–F12 failure taxonomy
  • Hooks and sandbox — the two enforcement planes (ACP semantic gate vs. OS sandbox), the 3-tier cross-harness coverage matrix, and config surfaces (.agentproto/hooks.json, .agentproto/command-sandbox.json)
  • Session transcripts — structured per-session capture, event kinds, native vs daemon export

Guides

File reference

Install

npm i -g @agentproto/cli
agentproto --version
agentproto --version --check-updates   # also compare against the published version on npm

--check-updates makes one npm registry call and prints an update hint only when a newer version is published; it prints nothing extra when already current or offline. --version alone stays instant and offline — safe in scripts and CI.

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.