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.

```bash
# 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 auto "implement the feature described in issue #42"
```

### Option B: Docker Compose

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

```bash
# 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 auto "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.

```bash
# 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:

```bash
# Terminal 1: auto mode
docker sandbox exec -it sf-sandbox bash
sf auto "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:

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

## Cleanup

```bash
# 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.