Dockerfile.sandbox

.veris/Dockerfile.sandbox packages your agent for the Veris sandbox. It’s a simulation-only Dockerfile — the image has to bundle your agent alongside everything the simulation needs: mock services, TLS certs, a PostgreSQL instance, and the Veris entrypoint that orchestrates it all.

Rather than make you install all of that, Veris publishes a base image with it pre-installed (Python 3.12, uv, Node.js, PostgreSQL, and all mock services). Your Dockerfile.sandbox is a thin layer on top: FROM the base image, install your dependencies, copy your code, end with WORKDIR /app so the Veris entrypoint can take over. Think of it as a sandbox image, not a production one.

Looking for complete working Dockerfiles? See the cookbook for full agent repos.

Anatomy

.veris/Dockerfile.sandbox


ARG VERIS_BASE
FROM ${VERIS_BASE}
 
# Install dependencies
COPY pyproject.toml uv.lock /agent/
WORKDIR /agent
RUN uv sync --frozen --no-dev
 
# Copy your code
COPY app /agent/app
 
WORKDIR /app

Every Dockerfile.sandbox does three things:

Extends the Veris base image. The ARG VERIS_BASE + FROM ${VERIS_BASE} lines are filled in automatically by veris env push.
Installs dependencies and copies your code into /agent. Use whatever package manager your stack already uses (pip, uv, poetry, npm, cargo, etc.).
Ends with WORKDIR /app. /app is where the Veris entrypoint lives; it takes over at container start.

Key paths

Path	Purpose
`/agent`	Where your code lives. Matches `agent.code_path` in `veris.yaml`.
`/certs`	Auto-generated TLS certificates. Your HTTP client trusts these via `SSL_CERT_FILE` / `NODE_EXTRA_CA_CERTS`.
`/app`	Veris infrastructure. Don’t write here.

Always end your Dockerfile with WORKDIR /app. /app is where the Veris entrypoint lives, and it takes over at container start to set up mocks, launch your agent via entry_point, and run the simulation. If you changed the working directory to install dependencies (e.g. WORKDIR /agent), switch it back with a final WORKDIR /app.

Build tips

Layer caching — copy dependency manifests first, install, then copy your code. Dependency installs stay cached when only code changes.
Multi-stage builds — if you compile in a separate stage (Go, Rust, Java, etc.), declare ARG VERIS_BASE before the first FROM so it’s available in the final stage’s FROM ${VERIS_BASE} line.
.dockerignore — the scaffolded .veris/.dockerignore excludes .git, .venv, node_modules, and other common noise. Add project-specific patterns as needed.
Platform — the sandbox runs on linux/amd64; veris env push handles cross-compilation.