singularity-forge/docker/README.md

SF Docker Sandbox

Run SF auto mode inside an isolated Docker sandbox so it cannot touch your host filesystem, SSH keys, or other projects.

Prerequisites

• Docker Desktop 4.58+ (macOS or Windows; Linux support is experimental)
• At least one LLM provider API key

Docker Images

File	Purpose
Dockerfile.sandbox	Runtime sandbox with entrypoint (UID remapping, bootstrap)
Dockerfile.ci-builder	CI builds — includes build tools, no entrypoint magic

Compose Files

File	Purpose
docker-compose.yaml	Minimal zero-config setup — just works with sensible defaults
docker-compose.full.yaml	Fully documented reference with all options, resource limits, health checks

Start with docker-compose.yaml. Copy options from docker-compose.full.yaml when you need them.

Quick Start

Option A: Docker Sandbox CLI (recommended)

Docker Sandboxes provide MicroVM isolation — each sandbox runs in a lightweight VM with its own kernel and private Docker daemon.

# Create a sandbox from the template
docker sandbox create --template ./docker --name sf-sandbox

# Shell into the sandbox
docker sandbox exec -it sf-sandbox bash

# Inside the sandbox, run SF
sf autonomous "implement the feature described in issue #42"

Option B: Docker Compose

For environments without Docker Sandbox support, use Compose for container-level isolation:

# 1. Configure API keys
cp docker/.env.example docker/.env
# Edit docker/.env with your keys

# 2. Start the sandbox
docker compose -f docker/docker-compose.yaml up -d

# 3. Shell into the container
docker exec -it sf-sandbox bash

# 4. Run SF inside the container
sf autonomous "implement the feature described in issue #42"

UID/GID Remapping

The entrypoint handles UID/GID remapping via PUID and PGID environment variables. This avoids permission issues on bind-mounted volumes by matching the container's sf user to your host UID/GID.

# Find your host UID/GID
id -u  # PUID
id -g  # PGID

Set these in your .env file or in the environment section of the compose file. Defaults to 1000:1000.

Entrypoint Behavior

The container entrypoint (entrypoint.sh) runs four steps on every start:

1. UID/GID remapping — adjusts the sf user to match PUID/PGID
2. Pre-create critical files — prevents Docker bind-mount from creating directories where files are expected
3. Sentinel-based bootstrap — runs bootstrap.sh exactly once on first boot
4. Drop privileges — exec gosu sf for proper PID 1 signal forwarding

No hardcoded user: directive in compose — the entrypoint starts as root, remaps, then drops to sf.

Two-Terminal Workflow

SF's recommended workflow uses two terminals — one for auto mode, one for interactive discussion:

# Terminal 1: auto mode
docker sandbox exec -it sf-sandbox bash
sf autonomous "your task description"

# Terminal 2: discuss / monitor
docker sandbox exec -it sf-sandbox bash
sf discuss

With Docker Compose, replace docker sandbox exec with docker exec.

Credential Injection

Docker Sandbox (automatic)

Docker's proxy layer forwards API keys set in your host shell config (~/.bashrc, ~/.zshrc) into the sandbox automatically. Keys are never stored inside the sandbox.

Docker Compose (manual)

Copy docker/.env.example to docker/.env and fill in your keys. The .env file is gitignored and never committed.

Network Allowlisting

If you restrict outbound network access in your sandbox, SF needs these endpoints:

Purpose	Endpoints
LLM APIs	api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, openrouter.ai
Package registry	registry.npmjs.org
Research tools	api.search.brave.com, api.tavily.com, r.jina.ai
GitHub	api.github.com, github.com

Customizing the Image

Build with a specific SF version:

docker compose -f docker/docker-compose.yaml build --build-arg SF_VERSION=2.51.0

Cleanup

# Docker Sandbox
docker sandbox rm sf-sandbox

# Docker Compose
docker compose -f docker/docker-compose.yaml down -v

Known Limitations

• macOS/Windows only: Docker Sandboxes require Docker Desktop 4.58+. Linux sandbox support is experimental.
• Environment parity: The sandbox runs Ubuntu (Debian). macOS-only dependencies may not work inside the sandbox.
• Named agent registration: Docker Desktop's built-in named agents (claude, codex, etc.) are registered by Docker itself. Third-party tools cannot register new named agents. SF uses the generic shell sandbox type with a custom template instead.