Debugging

How to inspect the running system using the arbe CLI. Covers rooms, agents, streams, and the worker — both local and deployed.

Setup

arbe debug reads secrets from environment variables, falling back to local env files (packages/www/.env, packages/www/.env.local, packages/worker/.dev.vars). No manual token passing needed.

Two auth contexts are in play:

User token — stored by arbe login, used for permission-checked API calls (rooms, agents, records). Required for most arbe debug subcommands.
Streams secret — DURABLE_STREAMS_SECRET, used for raw stream reads and worker endpoints. Read from env files automatically.

Inspecting rooms

arbe debug room <room-id>       # room record, house, stream ID, last 50 messages (with agent names)
arbe debug why <room-id>        # full diagnosis: agents, trigger modes, activations, messages, hints

arbe debug why is the go-to for “why isn’t the bot responding?” — it checks stream setup, agent presence, trigger modes, and recent activations in one shot.

Room IDs can be UUIDs or full URLs (https://arbe.land/room/...).

Inspecting agents

arbe debug agent <agent-id>     # agent record, kind, model, trigger mode, recent activations
arbe debug agents <scope-id>    # all agents in a room or house, with activations per bot

Creating resources

arbe debug create house <name>             # create a house, prints ID
arbe debug create room <house-id> <name>   # create a room in a house, prints ID
arbe debug create bot <house-id> <name>    # create a bot scoped to a house, prints agent ID + API key

Reading and writing messages

arbe debug messages <room-id>           # raw stream read (no auth, uses stream secret)
arbe debug postMessage <room-id> <text> # post a message through the app proxy (permission-checked, triggers bot dispatch)

postMessage goes through the same path as the browser — app proxy checks permissions, writes to the stream, dispatches to agents. Use it to trigger bot activations from the CLI.

Worker endpoints

arbe debug fetch <method> <path> [json-body]

Sends authenticated HTTP requests to the agents worker (AGENTS_URL, defaults to https://hus-agents.0skar.workers.dev). The streams secret is used as the bearer token.

Common endpoints:

arbe debug fetch GET /ping/<name>                    # verify DO is alive
arbe debug fetch GET /debug/<agent-id>               # full DO introspection (config, dedup, auth state)
arbe debug fetch GET /agent/<id>/activations?limit=5  # recent activation log
arbe debug fetch POST /activate/<agent-id> '{...}'   # manually fire an activation
arbe debug fetch POST /test-llm/<name> '{"durableStreamId":"room/<room-id>"}'  # test LLM round-trip

Typical debugging flows

Bot not responding to mentions:

arbe debug why <room-id> — check agents are in scope, trigger modes, stream ID exists
arbe debug fetch GET /debug/<agent-id> — check DO config, auth lockout, processed count
arbe debug fetch GET /agent/<id>/activations?limit=5 — check activation outcomes and errors
arbe debug postMessage <room-id> "@botname test" — trigger a fresh activation
Re-check activations for the new attempt

Checking stream connectivity:

arbe debug messages <room-id> — verify messages are in the stream
arbe debug postMessage <room-id> "test" — verify writes work

Worker health:

arbe debug fetch GET /ping/test — basic liveness check
arbe debug fetch GET /debug/<agent-id> — full state introspection

Running locally

The worker runs on port 8990 locally:

cd packages/worker
bun run dev                # starts wrangler dev on :8990

Requires a .dev.vars file with DURABLE_STREAMS_SECRET, ANTHROPIC_API_KEY, and SUPABASE_PUBLISHABLE_KEY. The www app dispatches to http://127.0.0.1:8990 when running on localhost (see agent-dispatch.ts).

Key files

File	What it does
`packages/cli/src/debug.ts`	All `arbe debug` subcommands
`packages/cli/src/auth.ts`	Token storage (`arbe login`)
`packages/worker/src/routes.ts`	Worker HTTP routes (activate, ping, debug, test)
`packages/worker/src/agent.ts`	HusAgent DO class
`packages/www/src/lib/server/agent-dispatch.ts`	Dispatch pipeline (www → worker)