Docs

Everything you need to run roam — self-hosted or hosted.

01Quickstart

Grab the binary and run your first agent in 60 seconds:

curl -fsSL https://github.com/javimosch/roam/releases/latest/download/roam-x86_64-linux -o roam
chmod +x roam
export ANTHROPIC_API_KEY="sk-ant-..."

./roam send --local --provider anthropic --allow-shell --confirm \
  --goal "list files in this directory and summarize the project"

./roam status last     # JSON snapshot
./roam attach last     # stream the journal live

For remote dispatch over SSH:

./roam send --to my-vm --provider anthropic --allow-shell --confirm \
  --goal "check disk usage and clean up logs older than 30 days"
./roam attach my-vm
./roam approve my-vm    # let the parked rm proceed
./roam stop my-vm       # cancel the agent

02How it works

1. roam send --local or roam send --to <host> creates a job.
2. The agent runs a tool loop: read_file, write_file, run_shell (gated by --allow-shell), finish.
3. Destructive commands (rm, git push --force, DROP TABLE…) park for approval.
4. You approve, deny, steer, or stop — from the terminal, the web panel, or a phone tap.
5. The worker ends in done, halted, stopped, or error.

03Providers

• --provider anthropic (default) — Anthropic Messages API. Key from ANTHROPIC_API_KEY or ROAM_API_KEY.
• --provider openai — any OpenAI-compatible endpoint (OpenRouter, etc.) via --api-base.
• --provider debri — delegates to the devin CLI (SWE-1.x models) via debri. Subscription-based, no per-token cost.

04Hosted hub

The hosted hub at roam.intrane.fr handles API keys, billing, and worker coordination. Workers hold no model keys — every LLM call goes through the hub's metered proxy.

Start a worker

roam worker --hub https://hub.roam.intrane.fr --token rhw_... \
  --label gpu=true --name gpu-box-01

Trigger a run

curl -X POST https://hub.roam.intrane.fr/t/<agent_id>/<secret> \
  -H "content-type: application/json" -d '{}'

Auto-provision a tenant

# any bearer token auto-creates a tenant — no signup needed
curl https://hub.roam.intrane.fr/v1/whoami \
  -H "authorization: Bearer my-random-token"

# attach an email for recovery + billing
curl -X POST https://hub.roam.intrane.fr/app/claim \
  -H "authorization: Bearer my-random-token" \
  -H "content-type: application/json" \
  -d '{"email":"you@company.com"}'

05Worker routing

Route specific agents to specific workers within a single tenant using selectors and labels.

"selector": "gpu=true,docker=true"

roam worker --hub ... --token ... \
  --label gpu=true \
  --label docker=true \
  --name gpu-box-01

Matching rules

• Empty selector = any worker (backward compatible)
• Worker with no labels = only gets runs with empty selector (backward compatible)
• All key=value pairs in the selector must be present in the worker's labels
• The claimed journal event includes the worker name when provided

Multiple workers

N workers can poll the same hub with the same rhw_ token. Each gets a different run from the queue — the hub's atomic claim guard prevents double-claiming. This is horizontal scaling: more workers = more parallel runs, all billed through one peage wallet.

06Billing

07Trust layer

• Hard budgets — --max-iters and --tokens freeze the run (status: halted) when hit.
• Confirm-gate — --confirm parks destructive commands for async approval.
• Deny budget — --max-denials (default 3) auto-halts an agent that keeps re-parking.
• Goal-verify — --verify sends finish to an independent judge that checks evidence.
• Workdir sandbox — file tools confined to ~/.roam/work/<jobid>/; .. and absolute paths refused.
• Append-only journal — every model turn, tool call, result, and token cost recorded.

08Worker failure handling

If a run has no worker activity for 15 minutes, the hub puts it back in the queue for another worker to pick up. After one reclaim attempt, the run is declared lost and billed only for what it actually metered. Your webhook (if set) receives the loss event.

09Self-hosting

The CLI is MIT-licensed. The approval panel is roam-panel — self-hostable with optional SSO via Portier. Bring your own Anthropic/OpenAI key, run workers on your own machines, approve from the panel or your terminal.

10Agent-first CLI

roam guide              # structured JSON: model, loop, concepts, examples
roam guide --human      # readable Markdown
roam help-json          # machine-readable commands, flags, exits
roam version            # version info
roam telemetry          # inspect opt-in telemetry state
roam update --check     # check for updates
roam feedback "..."     # send feedback

Controller errors use typed JSON on stderr and semantic exits: 80-89 for invalid input, 90-99 for missing resources or auth, 100-109 for remote/external failures.

11Telemetry

roam reports nothing unless you run roam telemetry --telemetry-on. A fresh install makes zero outbound connections beyond the work you asked it to do. If enabled, it sends version, os/arch, which verb ran and whether it failed — never prompts, keys, output, hostnames or paths.

12Hub API reference

For the full hub API (agents, runs, webhooks, LLM proxy, whoami, claim), see the Hub API reference.