Docker Deployment

Risoluto always launches agent workers in Docker containers. The orchestrator itself can run either directly on the host or inside its own container.

Project Structure

The repo ships three Dockerfiles:

Deployment Modes

Zero-Config (Wizard)
Pre-seeded Credentials
Host (No Docker for Orchestrator)

The simplest way to get started — no environment variables needed:

docker compose up --build

Open http://localhost:4000 and the setup wizard guides you through all credentials.

Named Volumes

Volume	Purpose
`risoluto-archives`	Encrypted secrets, config overlay, auth tokens, run archives
`risoluto-workspaces`	Cloned repositories for each issue
`codex-auth`	OpenAI Codex login tokens

For environments where you want to skip the wizard:

cp .env.example .env
# Fill in credentials and host paths
docker compose up --build

Key environment variables:

LINEAR_API_KEY=lin_api_...
LINEAR_PROJECT_SLUG=my-project
MASTER_KEY=your-encryption-key
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...

When MASTER_KEY is set before first boot, Risoluto skips setup mode and starts the orchestrator immediately.

Run the orchestrator directly on the host — only agent workers use Docker:

# 1. Install Node.js 22+ and Docker
# 2. Clone and build
git clone https://github.com/OmerFarukOruc/risoluto.git && cd risoluto
pnpm install && pnpm run build

# 3. Build the sandbox image
bash bin/build-sandbox.sh

# 4. Start — complete setup via the wizard
node dist/cli/index.js --data-dir /var/lib/risoluto --port 4000

For persistent operation, run Risoluto under systemd, tmux, or screen.

Container Behavior

Inside Docker, paths resolve differently:

Setting	Container Value	Purpose
`DATA_DIR`	`/data`	Archive root becomes `/data/archives`
`workspace.root`	`/data/workspaces`	Cloned repos live here inside the container
`RISOLUTO_BIND`	`0.0.0.0`	Listen on all interfaces (required inside Docker)

The PathRegistry automatically translates container paths back to host bind-mount sources before launching worker containers.

Docker Networking

Containers cannot reach the host’s 127.0.0.1. Risoluto automatically:

Adds --add-host=host.docker.internal:host-gateway to every worker container
Rewrites 127.0.0.1 to host.docker.internal in the Codex config.toml

If you use a host-side proxy like CLIProxyAPI, run it once on the host. All sandbox containers reach it over the Docker bridge network.

Control / Data Plane Split

For scale-out scenarios (remote workers, hot upgrades, multi-host), enable remote dispatch mode:

# .env
DISPATCH_MODE=remote
DISPATCH_URL=http://data-plane:9100/dispatch
DISPATCH_SHARED_SECRET=your-secure-secret-here

# Start both services
docker compose --profile full up --build

The data plane is not exposed to the host — it only listens on the private risoluto-internal bridge network.

Scenario	Benefit
Hot upgrades	Upgrade control plane without killing active agents
Multi-host workers	Data plane runs on remote hosts via SSH
Interactive workspaces	WebSocket proxy routes to correct data plane
Multi-repo orchestration	Multiple data planes with different checkouts

Remote dispatch is opt-in. The default DISPATCH_MODE=local runs everything in one process.

Custom Docker Networks

Attach worker containers to a specific network:

# config overlay
codex:
  sandbox:
    network: my-custom-network

This passes --network=my-custom-network to every docker run invocation.

gVisor Runtime

For defense-in-depth sandbox isolation, enable gVisor:

codex:
  sandbox:
    security:
      gvisor: true

Requires runsc installed on the Docker host. See the Security guide for details.

Egress Allowlists

Restrict outbound network access from worker containers:

codex:
  sandbox:
    egressAllowlist:
      - "api.openai.com"
      - "api.github.com"
      - "registry.npmjs.org"

Only listed domains are reachable from inside the sandbox.

Sandbox Image Tooling

The Dockerfile.sandbox image ships with:

Tool	Version	Purpose
Node.js	22 (via nodesource)	Runtime
Codex CLI	latest	AI agent execution
bubblewrap	system	Sandbox isolation (`--argv0`)
git	system	Source control
jq, ripgrep	system	JSON processing, search

The container runs as your user (--user $(id -u):$(id -g)) to avoid ownership drift on bind-mounted volumes.

Named Docker volumes survive container/image replacement but not docker system prune --volumes. Do not prune volumes prefixed with risoluto-.

Get Started

Core Concepts

Guides

Recipes

Operating

Docker Deployment

Project Structure

Deployment Modes

Named Volumes

Container Behavior

Docker Networking

Control / Data Plane Split

Sandbox Image Tooling

What’s Next

Setup Wizard

Configuration

​Project Structure

​Deployment Modes

​Named Volumes

​Container Behavior

​Docker Networking

​Control / Data Plane Split

​Sandbox Image Tooling

​What’s Next

Setup Wizard

Configuration

Project Structure

Deployment Modes

Named Volumes

Container Behavior

Docker Networking

Control / Data Plane Split

Sandbox Image Tooling

What’s Next