Task environment

The environment is the Linux system where the agent works. Install dependencies and seed files here; keep hidden tests in tests/.

Choose an image source

Dockerfile
Prebuilt image
Multiple containers

my-task/
└── environment/
    ├── Dockerfile
    └── input.csv

environment/Dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY input.csv /app/input.csv

Evolve builds the image when you publish the dataset. The build context is environment/, so COPY paths are relative to that directory.

task.toml

[environment]
docker_image = "python:3.12-slim"
workdir = "/app"

Use a public image with an explicit tag or digest. Untagged images and :latest are rejected. A prebuilt image takes precedence over environment/Dockerfile.If neither a Dockerfile nor Compose file is present, files under environment/ are uploaded to the working directory. These files must be UTF-8 text; put binary data inside the image.

my-task/
└── environment/
    ├── Dockerfile
    └── docker-compose.yaml

The file must be named environment/docker-compose.yaml. The agent runs in main; Evolve supplies that service from the task’s image or Dockerfile when you do not define it. Other services provide databases or other task dependencies.Compose runs on E2B or Daytona. Compose with no-network, GPUs, or multi-step tasks is not supported. Follow the multi-container guide for a complete environment example.

Working directory and user

The first available working directory wins:

Order	Source
1	`[environment].workdir`
2	The Compose `main` service’s `working_dir`
3	An absolute `WORKDIR` in `environment/Dockerfile`, or the Dockerfile selected by Compose `main.build`, even alongside a prebuilt `docker_image`
4	The image’s working directory, including one inherited from its base image
5	`/app`

When a prebuilt-image task declares environment.skills_dir and supplies those skill files under environment/, set workdir explicitly or use /app. Evolve does not substitute the image’s working directory in this case. The directory is recorded at publication; republish the same version label to update it.

Harbor and separate-verifier differences

Harbor’s Docker environment also uses inherited and prebuilt-image working directories. When the image declares no directory or uses /, Harbor runs at /; Evolve uses /app.A separate verifier resolves its directory in this order:

[verifier.environment].workdir when that table exists, otherwise [environment].workdir.
WORKDIR in tests/Dockerfile or the image it starts.
The image’s own working directory.
/app.

The Compose service setting does not apply to a separate verifier.

Use [agent].user to select an existing username. Otherwise, the parsed Dockerfile’s USER applies, with root as the fallback. Use root or 0 for root; other numeric UIDs and user:group declarations are rejected. The named user must already exist in the image, and the image must include su. Evolve prepares the user’s home before running the agent. Non-root users require a built-in harness; registered custom agents do not support them.

task.toml

[agent]
user = "dev"

[environment]
workdir = "/workspace"

Start a service

An image’s ENTRYPOINT runs before the agent starts. CMD is not used as the task command; keep-alive entrypoints such as sleep infinity do not start a service. Add a healthcheck when the agent must wait for a service:

task.toml

[environment.healthcheck]
command = "curl -fsS http://localhost:8000/health"
interval_sec = 5
timeout_sec = 30
start_period_sec = 0
start_interval_sec = 5
retries = 3

The agent starts after the check exits 0. Exhausted retries fail the trial before the agent runs. The values above are the defaults; only command is required.

A separate verifier cannot reuse an agent image that starts a service. Give it its own verifier image, or use shared verification.

Add MCP tools

Declare servers in task.toml for a built-in harness with MCP support. Registered custom agents and mini-swe-agent do not support task MCP servers.

[[environment.mcp_servers]]
name = "docs-search"
transport = "streamable-http"
url = "https://tools.example.com/mcp"

[[environment.mcp_servers]]
name = "sqlite"
transport = "stdio"
command = "mcp-server-sqlite"
args = ["--db-path", "/app/data.db"]

A remote URL must be reachable under the task’s network policy. A local process must be installed in the image; downloading it with npx or uvx needs network access. stdio processes inherit the task environment variables and do not accept a separate env field.

Supported scope

Evolve runs headless Linux tasks. It does not provide a desktop, display server, Windows environment, or Apptainer runtime.

Configure the task

Set resources, timeouts, and network access.

Start here

Run evaluations

Task format

Validate your work

Read results

Work together

Task environment

Choose an image source

Working directory and user

Start a service

Add MCP tools

Supported scope

Configure the task