Custom sandbox images

Sagewai ships seven pre-built sandbox variants (base, general, ml, ops, erp, ecommerce, api) at ghcr.io/sagewai/sandbox-<variant>. When you need tooling that none of those variants include — a specific CLI, a private wheel, a GPU runtime, or a smaller image — build your own and point sagewai worker start --sandbox-image at it.

This page covers the requirements your image must satisfy, a copy-paste Dockerfile template, and the validation step.

Requirements

Your image must:

  1. Include sagewai-tool-runner at a version satisfying this SDK's TOOL_RUNNER_VERSION_SPEC (currently >=0.1,<0.2). The binary must be on PATH as sagewai-tool-runner.
  2. Use tini (or equivalent) as PID 1, with a long-lived command so the container stays alive. ENTRYPOINT ["/usr/bin/tini", "--"] combined with CMD ["sleep", "infinity"] works.
  3. Set WORKDIR to /workspace, and leave it writable by the root user. Sagewai mounts the scratch directory there.

Your image should:

  • Inherit from ghcr.io/sagewai/sandbox-base:<your-sdk-version> — this satisfies all three requirements above.
  • Keep the root filesystem read-only at runtime. Sagewai already enforces this, so avoid writing to /etc, /usr, or similar paths during execution.
  • Document the tools you added in the image's README.md so operators know what is available.

Template

# syntax=docker/dockerfile:1.7

# Pin the exact SDK version whose worker will schedule against this image.
FROM ghcr.io/sagewai/sandbox-base:0.1.5 AS runner

USER root

# Example: add your internal CLI.
RUN curl -fsSL -o /tmp/mycli.tar.gz \
      "https://example.com/mycli-1.0.0-linux-amd64.tar.gz" \
  && echo "<sha256>  /tmp/mycli.tar.gz" | sha256sum -c \
  && tar -xzf /tmp/mycli.tar.gz -C /usr/local/bin \
  && rm /tmp/mycli.tar.gz

# Example: add a private pip package with hash pinning.
COPY requirements-internal.txt /tmp/
RUN pip install --no-cache-dir --require-hashes -r /tmp/requirements-internal.txt \
  && rm /tmp/requirements-internal.txt

# Do not overwrite ENTRYPOINT or CMD — the base image's config is what tool-runner expects.

Validate before shipping

Run sagewai sandbox validate against your image before wiring it into a project. The command pulls the image, probes the runner, and confirms the full sandbox lifecycle:

sagewai sandbox validate ghcr.io/your-org/your-sandbox:1.0

A compatible image prints six check lines:

  ✓ image pulled (digest sha256:...)
  ✓ container starts
  ✓ sagewai-tool-runner --version → 0.1.0 (compatible)
  ✓ bash echo round-trip → 42 ms
  ✓ /workspace writable
  ✓ env scrub: HOST_SECRET not visible
  PASS — image is compatible with this SDK

Failures exit non-zero with a specific remediation message. The most common error — sagewai-tool-runner not found in PATH — usually means /usr/local/bin was stripped from your image. Re-inherit from sandbox-base and retry.

Pointing workers at a custom image

Two ways to use your image:

# Worker-default: applies to every run this worker claims
sagewai worker start --sandbox-image ghcr.io/your-org/your-sandbox:1.0 …

# Agent-scoped: applies only to this agent
# In your agent spec YAML: sandbox_image: ghcr.io/your-org/your-sandbox:1.0

Custom images skip SDK-level digest verification (they are not in the Sagewai manifest). On first use, Sagewai logs a single INFO line with the resolved digest so auditors can reconstruct what actually ran. Treat sagewai sandbox validate as your trust anchor for these images.

Keeping image size down

The general variant weighs ~900 MB — Playwright and Chromium dominate. If you do not need browser automation, inherit from base directly and add only what your agents require. A minimal web-scraping image can come in at ~300 MB.