{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://www.aarmos.io/docs/aarmos-cli-contract.v0.1.json", "title": "Aarmos CLI + Adapter Contract", "description": "Machine-readable contract for @aarmos/cli v0.1 and the three protocol adapters. This document is the spec Workstream B builds against — the /docs pages are the human-readable projection of the same contract. Do not diverge without bumping the version and updating both.", "version": "0.1.0-draft", "status": "draft", "promises": { "c1_no_agent_data_leaves_device": "No Aarmos-hosted service ever proxies or sees agent data. The `aarmos proxy` daemon runs on 127.0.0.1 and forwards to the ORIGINAL destination the agent already called — never to an Aarmos endpoint.", "c2_avar_on_every_run": "Every execution path — `aarmos run`, `aarmos proxy`, adapter invocations — writes to the same local AVAR chain. No path bypasses receipts.", "c3_byos_pointer_only": "License activation + team-membership pointers are the ONLY things that ever touch an Aarmos-hosted server. Never AVAR entries, prompts, tool-call arguments, policy bodies, or workspace contents.", "c4_daemon_is_local_only": "`aarmos daemon` and `aarmos proxy` bind 127.0.0.1 only, never a public interface. No per-request phone-home to Aarmos-owned hosts (license refresh is a background pointer-only check, never carries request payloads)." }, "correction_locks": { "correction_1_protocols_not_frameworks": "Adapters span protocols (MCP, OpenAPI, deep-link/webhook) and the transparent local proxy (`aarmos proxy`). Never LangChain, LlamaIndex, AutoGen, CrewAI, Swarm, or OpenAI-SDK wrappers as headline features. Framework support is a consequence of protocol brokerage, not a shipped SDK.", "correction_2_avar_on_every_run": "Every `aarmos run` invocation MUST print an AVAR receipt path and verify command on stdout. Not a flag. Not optional. Not later. `aarmos proxy` writes to the same chain.", "correction_3_lead_copy": "Run your agent locally, across any protocol, with a signed receipt — in 60 seconds." }, "install_paths": [ { "method": "npm", "command": "npm i -g @aarmos/cli" }, { "method": "homebrew", "command": "brew install aarmatix/tap/aarmos", "tap_repo": "aarmatix/homebrew-tap" }, { "method": "shell", "command": "curl -fsSL https://get.aarmos.io | sh", "supported_os": ["macos", "linux"] } ], "cli_commands": { "init": { "invocation": "aarmos init", "writes": [ "policy.aarmos.toml", "avar.config.json", ".aarmos/keys/ (Ed25519 signing key, gitignored)" ], "does_not_write": [ "agent code — Aarmos runs the agent you already have; init scaffolds POLICY, not code. Code scaffolding is an anti-pillar violation (coding-agent IDE)." ] }, "run": { "invocation": "aarmos run ", "required_stdout_footer": "✓ AVAR receipt: \n verify: avar verify ", "per_tool_call_stdout_shape": "▸ tool: :/// (adapter: ) ", "statuses": ["✓ scoped", "✓ scoped, confirm", "✓ cached — 0 tokens", "✗ refused: "] }, "proxy": { "invocation": "aarmos proxy [--port 7681]", "purpose": "Transparent local HTTP proxy on 127.0.0.1. Any client that emits HTTP (LangChain, AutoGen, CrewAI, Swarm, custom scripts) enrolls with zero code changes by setting `HTTPS_PROXY=http://127.0.0.1:7681` or an OpenAI-compatible `BASE_URL`. Aarmos brokers the outbound call under the same policy substrate as `aarmos run`, writes the same AVAR chain, and forwards to the ORIGINAL destination.", "bind_address": "127.0.0.1", "must_not_carry": [ "Any pointer to Aarmos-hosted services in the request path — the proxy forwards to the client's original destination only", "Per-request phone-home to Aarmos-owned hosts (no license check, telemetry, or receipt upload in the request path)" ], "framework_adapter_ban": "This command is the ENTIRE framework-integration surface. Do not ship `@aarmos/langchain`, `@aarmos/autogen`, `@aarmos/crewai`, `@aarmos/swarm`, or any framework-named package as a headline feature. Zero lines of code beats three." }, "daemon": { "invocations": ["aarmos daemon start", "aarmos daemon stop", "aarmos daemon status"], "bind_address": "127.0.0.1" }, "verify": { "invocation": "aarmos verify ", "note": "Verifies an AVAR receipt locally (.avar.zip bundle or legacy .json) — Ed25519 signatures + hash chain via @aarmos/avar-core. Works with the Aarmos daemon stopped. Zero network. The standalone `avar` binary is the cross-runtime spec-canonical reference and ships alongside." } }, "adapters": { "mcp": { "package": "@aarmos/adapter-mcp", "toml_shape": { "table": "[[adapters.mcp]]", "required": ["name", "url", "scopes"], "optional": ["gates.destructive", "rate.per_minute"] }, "tool_scheme": "mcp:///", "doc_route": "/docs/adapters/mcp" }, "openapi": { "package": "@aarmos/adapter-openapi", "toml_shape": { "table": "[[adapters.openapi]]", "required": ["name", "scopes"], "one_of": ["spec", "url"], "optional": ["gates.destructive", "rate.per_minute"] }, "tool_scheme": "openapi:///", "scope_rule": "Every method+path is a distinct scope. Writes require an explicit write scope.", "doc_route": "/docs/adapters/openapi" }, "deeplink": { "package": "@aarmos/adapter-deeplink", "toml_shape": { "table": "[[adapters.deeplink]]", "required": ["name", "scopes"], "one_of": ["scheme", "url"], "optional": ["method", "gates.destructive", "rate.per_minute"] }, "tool_scheme": "deeplink:///", "doc_route": "/docs/adapters/deeplink" } }, "compatibility_matrix_doc_route": "/docs/compatibility", "avar_receipt": { "spec_version": "0.1", "spec_route": "/docs/avar-spec", "signature_alg": "ed25519", "hash_alg": "sha256", "portability_guarantee": "Verifies against nothing but the Ed25519 public key that signed it. No Aarmos service dependency. No proprietary parser. Open, unencumbered.", "must_not_carry": [ "Prompts, chats, or tool-call arguments in the clear", "User credentials or vault contents", "Any pointer to Aarmos-hosted services" ] }, "quickstart_video": { "target_duration_seconds": 60, "target_upper_bound_seconds": 75, "script_source_of_truth": "/docs/quickstart", "must_show": [ "Install (one command)", "aarmos init writing policy, not code", "aarmos run with 3 distinct protocols in one invocation", "Second run cached — 0 LLM tokens", "AVAR receipt path + verify command on stdout", "aarmos daemon stop followed by avar verify succeeding" ], "must_not_show": [ "Any framework-specific wrapper (LangChain, LlamaIndex, AutoGen, CrewAI, Swarm, OpenAI SDK) as the headline surface", "Cloud-hosted execution", "Voice-over marketing copy — terminal-only" ] } }