# 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`
- `GET /chats/:chatId/history-page?limit=<count>` (`limit` required)
- `GET /chats/:chatId/slash-commands`
- `POST /chats/:chatId/messages`
- `POST /chats/:chatId/interrupt`

Canvas:

- `GET /canvas`
- `GET /canvas/: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/sandbox-helpers.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>`
- Managed Git credential helper setup when code-host tokens are available:
  - `git config --global credential.helper ~/.git-credential-replicas`
  - `~/.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):
  - OAuth access tokens are supplied through Codex ASP external authentication.
  - Provisioning writes `~/.codex/auth.json` for older engines; current engines remove it before starting Codex.

Token refresh managers may later overwrite credential files in place:

- `~/.git-credentials`
- `~/.claude/.credentials.json`
- `~/.codex/auth.json` (removed by current engines before Codex starts)
- `~/.replicas/infisical-env.sh` and `~/workspaces/.infisical.json`

Engine persistence locations:

- `~/.replicas/engine/chats.json`
- `~/.replicas/engine/events.jsonl`
- `~/.replicas/engine-state.json`
- `~/.replicas/startHooks.log`
- Canvas read locations (for `/canvas` endpoints):
  - `~/.claude/plans` (where Claude Code writes its plans)
  - `~/.local/share/opencode/plans` and each repository's `.opencode/plans`
  - `~/.replicas/canvas`
- 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 OAuth uses ASP external authentication; the engine removes legacy `~/.codex/auth.json` files.

## What the engine sends upstream

The engine calls monolith with:

- `Authorization: Bearer <REPLICAS_ENGINE_SECRET>`
- `X-Workspace-Id: <REPLICAS_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`
- `POST /v1/engine/infisical/refresh-token`
- `POST /v1/engine/chat-turn-activity`
- `POST /v1/engine/skill-activity`
- `POST /v1/engine/mcp-activity`

The previous `chat-turn-usage`, `skill-usage`, and `mcp-usage` paths remain accepted for older engine versions.