Skip to main content

​
Custom Sandbox Image

The default risoluto-codex:latest image ships with Node.js 22, Codex CLI, Git, and common developer tools. When your project needs extra runtimes or tooling, build a custom image.

​
When you need this

  • Your project uses Python, Go, Rust, Java, or other runtimes
  • You want project dependencies pre-installed for faster agent startup
  • You need specialized CLIs (terraform, kubectl, aws, gcloud)
  • You want a reproducible, locked-down agent environment

​
Build a custom image

1

Create a Dockerfile

Extend the base image with your tools.
FROM risoluto-codex:latest

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 python3-pip python3-venv \
  && rm -rf /var/lib/apt/lists/*

RUN pip3 install --break-system-packages poetry ruff mypy
2

Build the image

docker build -f Dockerfile.custom -t risoluto-codex-custom:latest .
3

Configure Risoluto to use it

curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"sandbox":{"image":"risoluto-codex-custom:latest"}}}'
4

Verify

Create a test issue and confirm the container uses your image:
docker ps --filter label=risoluto.issue --format '{{.Image}} {{.Names}}'
# Expected: risoluto-codex-custom:latest risoluto-MT-42-abc123

​
Pre-installing dependencies

Bake your project’s dependency tree into the image for faster agent startup:
Dockerfile.with-deps
FROM risoluto-codex:latest

COPY package.json pnpm-lock.yaml /tmp/project/
RUN cd /tmp/project && pnpm install --frozen-lockfile
Then mount the installed dependencies as read-only: 
curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"sandbox":{"extraMounts":["/tmp/project/node_modules:/workspace/node_modules:ro"]}}}'

​
Advanced options

gVisor intercepts syscalls, providing an additional isolation layer between the agent and the host kernel.
curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"sandbox":{"security":{"gvisor":true}}}}'
Prerequisites: runsc must be installed on the host and registered as a Docker runtime. gVisor adds latency overhead but is recommended for untrusted workloads.
Restrict which domains the agent container can reach:
curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"sandbox":{"network":{"egressAllowlist":["registry.npmjs.org","api.github.com"]}}}}'
Any outbound connection to a domain not on the list is blocked.
Mount host directories into the container for shared caches, config files, or read-only data:
curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"sandbox":{"extraMounts":["/home/user/.cache/pip:/root/.cache/pip:ro","/etc/custom-tools:/opt/tools:ro"]}}}'
Forward specific host environment variables into the sandbox:
curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"sandbox":{"envPassthrough":["DATABASE_URL","REDIS_URL","AWS_PROFILE"]}}}'
Only forward variables the agent genuinely needs. Every forwarded variable is accessible to the AI inside the container.
Custom images bypass the default security baseline. When extending the image, avoid installing setuid binaries, running as root unnecessarily, or opening additional network ports. Review your Dockerfile against the Trust Model before deploying.

​
What’s Next

Multi-repo Setup

Route issues to different repos with prefix and label matching.

Monitoring Stack

Set up Prometheus and Grafana to monitor agent runs.

Trust Model

Understand the sandbox security boundaries.
Last modified on March 31, 2026