Skip to Content
ConfigurationDockerfile

Dockerfile Reference

The .veris/Dockerfile.sandbox extends the Veris base image with your agent’s code and dependencies. The base image already includes all mock services, the simulation engine, the actor, nginx, TLS infrastructure, and PostgreSQL.

Your Dockerfile only needs to:

  1. Copy your dependencies and install them
  2. Copy your agent code
  3. Optionally copy database schemas or scenarios
  4. Set WORKDIR /app as the final instruction

Base Image

FROM us-central1-docker.pkg.dev/veris-ai-prod/veris-sandbox/veris-gvisor:latest

The base image includes:

  • Python 3.12 with uv package manager
  • PostgreSQL 16
  • Node.js (for JavaScript-based services)
  • nginx (TLS termination and reverse proxy)
  • All mock services pre-installed
  • Simulation engine and actor service
  • LLM proxy for tracing
  • Entrypoint orchestration script

Examples

Python with pip

.veris/Dockerfile.sandbox
FROM us-central1-docker.pkg.dev/veris-ai-prod/veris-sandbox/veris-gvisor:latest
 
COPY requirements.txt /agent/
RUN pip install -r /agent/requirements.txt
 
COPY app /agent/app
 
WORKDIR /app

Python with uv

.veris/Dockerfile.sandbox
FROM us-central1-docker.pkg.dev/veris-ai-prod/veris-sandbox/veris-gvisor:latest
 
COPY pyproject.toml uv.lock /agent/
WORKDIR /agent
RUN uv sync --frozen --no-dev
 
COPY app /agent/app
 
WORKDIR /app

Python with poetry

.veris/Dockerfile.sandbox
FROM us-central1-docker.pkg.dev/veris-ai-prod/veris-sandbox/veris-gvisor:latest
 
COPY pyproject.toml poetry.lock /agent/
WORKDIR /agent
RUN pip install poetry && poetry install --no-dev --no-interaction
 
COPY app /agent/app
 
WORKDIR /app

With database schemas

.veris/Dockerfile.sandbox
FROM us-central1-docker.pkg.dev/veris-ai-prod/veris-sandbox/veris-gvisor:latest
 
COPY requirements.txt /agent/
RUN pip install -r /agent/requirements.txt
 
COPY app /agent/app
COPY schemas /agent/schemas
 
WORKDIR /app

With scenarios

.veris/Dockerfile.sandbox
FROM us-central1-docker.pkg.dev/veris-ai-prod/veris-sandbox/veris-gvisor:latest
 
COPY requirements.txt /agent/
RUN pip install -r /agent/requirements.txt
 
COPY app /agent/app
 
WORKDIR /app

Key Paths Inside the Container

PathPurpose
/agentYour agent code (configurable via agent.code_path)
/scenariosScenario YAML files
/config/veris.yamlRuntime configuration (mounted automatically)
/sessions/{id}Simulation logs and artifacts
/certsAuto-generated TLS certificates and mock service accounts
/appVeris infrastructure (do not modify)

Always end your Dockerfile with WORKDIR /app. The Veris entrypoint script expects to run from /app. If you change the working directory to install dependencies (e.g., WORKDIR /agent), make sure to switch back.

Container Startup Sequence

When the container starts, the entrypoint script orchestrates the following:

  1. Parse veris.yaml configuration
  2. Configure DNS aliases in /etc/hosts
  3. Generate TLS certificates (CA + server certificates with SANs)
  4. Generate mock service accounts (e.g., Google service account JSON)
  5. Start nginx for TLS termination
  6. Inject CA certificates into Python trust stores
  7. Start mock services (PostgreSQL and LLM proxy get health checks)
  8. Start your agent using the configured entry_point
  9. Wait for all services and your agent to be healthy (120s timeout)
  10. Start the simulation engine
  11. Poll for simulation completion
  12. Save logs and artifacts

Build Tips

  • Layer caching — Copy dependency files first, install them, then copy your code. This way dependency installation is cached when only code changes.
  • .dockerignore — The generated .veris/.dockerignore excludes .git, .venv, node_modules, and other common artifacts. Edit it if your project has other large directories to exclude.
  • Platform — The sandbox runs on linux/amd64. On Apple Silicon Macs, the CLI automatically uses docker buildx for cross-compilation.
  • Size limit — Build context is capped at 500 MB when using --remote. Keep your build context lean.
veris.yamlCI/CD Integration