Skip to main content

Customize the agent runtime

Agents sometimes need tools that are not in the default runtime: a browser like Chromium, the gh CLI, a custom certificate, or an extra system package.

Where you add them depends on where the agent code runs. This is the part teams get wrong.

  • Local runs execute inside the runner container. The runner service image is the local sandbox, so you customize that image.
  • Daytona runs execute inside a Daytona cloud sandbox. You customize the snapshot the sandbox starts from.

Read How agents run if that distinction is new.

Add dependencies for Daytona runs​

Build a custom snapshot with the shipped recipe and add your dependencies to it, then point the runner at your snapshot. This is the same flow as Run agents in a cloud sandbox (Daytona), with your extra build steps.

  1. Copy the recipe in services/runner/images/sandbox/daytona/build_snapshot.py.

  2. Add your dependencies to its dockerfile_commands list (for example an apt-get install line or a binary download).

  3. Build it in your Daytona account:

    cd services/runner/images/sandbox/daytona
    DAYTONA_API_KEY=<daytona-api-key> DAYTONA_TARGET=eu uv run build_snapshot.py --force

  4. Point the runner at the snapshot:

    AGENTA_RUNNER_DAYTONA_SNAPSHOT=agenta-agent-sandbox-v1

Sandbox size​

The snapshot recipe sets the compute and disk each Daytona sandbox gets. The defaults suit most runs, and you set them with build-time environment variables:

VariableDefaultControls
AGENTA_SANDBOX_CPU2vCPUs per sandbox
AGENTA_SANDBOX_MEMORY_GB4Memory (GB) per sandbox
AGENTA_SANDBOX_DISK_GB5Local disk (GB) per sandbox
cd services/runner/images/sandbox/daytona
AGENTA_SANDBOX_DISK_GB=10 \
  DAYTONA_API_KEY=<daytona-api-key> DAYTONA_TARGET=eu uv run build_snapshot.py --force

A new value takes effect only when you rebuild the snapshot, so it never touches sandboxes that are already running. Raise the disk if your runs write large working files: the session working directory mounts from the durable store, so local disk holds the image plus temporary files, and 5 GB leaves a few GB of working headroom on top of the built image. Keep the CPU and memory generous, since agents spike during builds and an out-of-memory kill mid-run is a poor experience.

Add dependencies for local runs​

Build a custom runner service image from the shipped Dockerfile and add your dependencies to it. This also pins your own runner build.

  1. Build from the repository root:

    docker build \
      -f services/runner/images/service/Dockerfile.gh \
      -t <registry>/agenta-runner:<tag> \
      services/runner

    Add your RUN apt-get install ... or COPY steps to a copy of Dockerfile.gh before building. The published image does not bundle Claude Code; if a harness needs Claude Code, the runner installs it from Anthropic at runtime.

  2. Point the runner service at your image with a Compose override file (docker-compose.override.yml):

    services:
      runner:
        image: <registry>/agenta-runner:<tag>

    For Helm, set the runner image in your values file under agentRunner.

Add project folders for local runs​

To make extra folders available inside local agent runs, mount them into the runner container with a Compose override. This is an operator-owned mount, not an Agenta feature.

services:
  runner:
    volumes:
      - ./my-tools:/opt/my-tools:ro

This affects local runs only. Daytona sandboxes do not see host volumes; bake the files into a snapshot instead.