Cloud Agents

@bonsai/cloud-agents is a local self-hosted control plane for coding-agent runs. It gives devgraph, Codex, and Claude runs one normalized CLI surface, run store, inbox, status format, blocker format, logs view, and diff artifact contract.

Despite the name, V1 is local. It does not include Kubernetes, remote workers, multi-tenant auth, or a hosted web UI.

Core Concepts

• Agent adapters launch and inspect different backends through one interface.
• LocalRunStore persists run artifacts under .lifecycle/runs/<run-id>/.
• Inbox groups blocked, failed, interrupted, running, unknown, and done runs across all producers.
• Blockers are structured blocker.json files with a required question and optional context/options.
• Answers are written as answer.json so the producer can resume without clobbering its own status file.

Supported Agents

Agent	Use	Notes
devgraph	Default lifecycle runner.	Requires devgraph on PATH, CLOUD_AGENTS_DEVGRAPH_REPO, or CLOUD_AGENTS_DEVGRAPH_CMD.
codex	Headless Codex run through the normalized graph.	Uses Codex CLI auth. Defaults to the CLI's read-only behavior unless CLOUD_AGENTS_CODEX_SANDBOX is set.
claude	Headless Claude run through the normalized graph.	Requires ANTHROPIC_API_KEY or another supported Claude provider mode.

Install and Develop

cd apps/cloud-agents
bun install
bun run build

Development checks:

bun test
bun run typecheck
bun run build

Prerequisites

Default devgraph runs:

• devgraph available through one of the configured resolution modes.
• tmux for detached devgraph launches.
• Devgraph project config and its provider prerequisites.

Codex runs:

• codex on PATH.
• Saved Codex CLI auth, or credentials accepted by codex exec.
• Optional CLOUD_AGENTS_CODEX_SANDBOX=workspace-write when a run should edit files.

Claude runs:

• @anthropic-ai/claude-agent-sdk installed with the package.
• ANTHROPIC_API_KEY, or provider-specific Claude configuration such as Bedrock, Vertex, AWS, or Foundry.
• Optional CLOUD_AGENTS_CLAUDE_ALLOWED_TOOLS=Read,Glob,Grep,Edit,Write.
• Optional CLOUD_AGENTS_CLAUDE_PERMISSION_MODE=acceptEdits.

Commands

cloud-agents agents

cloud-agents run "summarize this repo and suggest one safe improvement"
cloud-agents run "summarize this repo and suggest one safe improvement" --agent codex
cloud-agents run "summarize this repo and suggest one safe improvement" --agent claude

cloud-agents inbox
cloud-agents inbox --json

cloud-agents status <run-id>
cloud-agents logs <run-id>
cloud-agents diff <run-id>

cloud-agents doctor
cloud-agents doctor --agent codex
cloud-agents doctor --agent claude

Blocker commands:

cloud-agents block <run-id> "Which search backend?" \
  --context "no search dependency exists yet" \
  --option "SQLite FTS5" \
  --option "Meilisearch"

cloud-agents resolve <run-id> "Use SQLite FTS5"

Inbox Output

The inbox is the main triage surface. Blocked runs are listed first because they need a human answer.

inbox - 3 runs (1 blocked, 1 failed, 1 done)

BLOCKED - needs you (1)
  - 20260617-100001-add-search  [devgraph]  add full-text search
      ? Which search backend should I use?
        context: no search dep in package.json yet
        options:
          1. SQLite FTS5
          2. Meilisearch
      resolve: cloud-agents resolve 20260617-100001-add-search "<answer>"

Use --json for machine-readable inbox data.

Artifact Layout

.lifecycle/runs/<run-id>/
  status.json
  events.ndjson
  stdout.log
  stderr.log
  summary.md
  patch.diff
  metadata.json
  blocker.json
  answer.json

status.json uses the normalized status shape:

run:    20260616-010203-summarize-this-repo
agent:  codex
state:  done
stage:  finalize
last:   done @ finalize

summary.md and patch.diff are written when available. cloud-agents logs prefers rendered events and falls back to stdout/stderr logs. cloud-agents diff prints patch.diff or a clear no-diff message.

Devgraph Resolution

The devgraph adapter resolves how to invoke devgraph in this order:

1. CLOUD_AGENTS_DEVGRAPH_CMD
2. devgraph on PATH
3. bun <CLOUD_AGENTS_DEVGRAPH_REPO>/src/cli.ts

Set one of these when cloud-agents doctor reports that devgraph is missing.

Safety and Limits

• V1 defaults are conservative and local.
• Codex runs use the CLI's default sandbox unless CLOUD_AGENTS_CODEX_SANDBOX changes it.
• Claude runs default to read-oriented tools and dontAsk permission mode unless configured otherwise.
• resolve does not clobber producer-owned status files; it writes an answer and removes blocker markers.
• V1 intentionally omits remote worker orchestration, Postgres, Redis, Temporal, object storage, hosted auth, PR publishing, and observability.