Replicas Engine (V1)

Replicas Engine is the workspace runtime that powers coding agents.

Authorization Header: X-Replicas-Engine-Secret: <REPLICAS_ENGINE_SECRET>

Core Flow:

1. Fetch snapshots (/status, /chats, /repos, /hooks/status).
2. Open GET /events for deltas.
3. Send messages via POST /chats/:chatId/messages.

Engine API surface (v1)

System:

• GET /health
• GET /status
• GET /token-refresh/health

Stream:

• GET /events (SSE)

Chats:

• POST /chats
• GET /chats
• GET /chats/:chatId
• DELETE /chats/:chatId
• GET /chats/:chatId/history
• POST /chats/:chatId/messages
• POST /chats/:chatId/interrupt

Plans:

• GET /plans
• GET /plans/:filename

Repos and hooks:

• GET /repos
• GET /repos?includeDiffs=true (includes gitDiff.fullDiff)
• GET /hooks/status

SSE envelope:

• id: stable event id
• event: engine event type
• data: JSON-serialized EngineEvent

VM/runtime contract

The engine is expected to run in a VM/sandbox with:

• OS user with writable home (default /home/ubuntu)
• Workspace root at ~/workspaces
• Git available in PATH
• gh CLI available in PATH (for PR URL discovery)
• Claude and Codex CLIs installed/configurable

Provisioning contract (what monolith injects before engine start)

From monolith/src/lib/daytona.ts + monolith/src/lib/workspaces.ts, the VM is expected to be prepped with:

• Git identity (optional but expected for commits):
  • git config --global user.name <bot-or-user-name>
  • git config --global user.email <bot-or-user-email>
• Git credential helper setup when GitHub token is available:
  • git config --global credential.helper store
  • ~/.git-credentials with https://x-access-token:<token>@github.com
• Repository materialization:
  • clone repositories into /home/ubuntu/workspaces/<repo-name>
  • if no repository URL is provided, create empty /home/ubuntu/workspaces/<repo-name>
• Claude credentials (optional):
  • file: ~/.claude/.credentials.json
  • source: OAuth credential object provisioned by monolith
• Bedrock credentials (optional):
  • file: ~/.claude/.bedrock-credentials.json
  • env: CLAUDE_CODE_USE_BEDROCK=1, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
• Codex credentials (optional):
  • file: ~/.codex/auth.json
  • format includes tokens.id_token, tokens.access_token, tokens.refresh_token, tokens.account_id

Token refresh managers may later overwrite credential files in place:

• ~/.git-credentials
• ~/.claude/.credentials.json
• ~/.codex/auth.json

Engine persistence locations:

• ~/.replicas/engine/chats.json
• ~/.replicas/engine/events.jsonl
• ~/.replicas/engine-state.json
• ~/.replicas/startHooks.log
• Plan read locations (for /plans endpoints):
  • ~/.claude/plans
  • ~/.replicas/plans
• Health endpoint readiness signal file:
  • /var/log/cloud-init-output.log (if missing, /health reports initializing)

Environment contract

src/engine-env.ts is the source of truth for engine runtime environment variables.

Use that file to understand:

• required vars (boot-time validated)
• optional vars used by engine code
• ambient/runtime vars captured for SDK/CLI/agent compatibility

Engine env vars are injected by monolith when the engine is started inside sandboxes.

Credential files expected/used by provider CLIs:

• ~/.git-credentials (git/gh auth)
• ~/.claude/.credentials.json (Claude OAuth auth)
• ~/.claude/.bedrock-credentials.json (Claude Bedrock config)
• ~/.codex/auth.json (Codex auth)

What the engine sends upstream

The engine calls monolith with:

• Authorization: Bearer <REPLICAS_ENGINE_SECRET>
• X-Workspace-Id: <WORKSPACE_ID>

Outgoing endpoints:

• POST /v1/engine/webhook
• POST /v1/engine/github/refresh-token
• POST /v1/engine/claude/refresh-credentials
• POST /v1/engine/codex/refresh-credentials