task.toml file specifies the task configuration and metadata.
[environment] vs. environment/
By default, Harbor defers as much configuration as possible into the environment/ spec rather than the task.toml. A lot of engineering effort has gone into designing environment/ specs (like Dockerfile) and they provide conventions for common use cases.
Only when absolutely necessary does Harbor require configuration in the task.toml.
A few fields in task.toml are due to lack of convention or common pitfalls:
Field reference
General
string
default:"\"1.3\""
Version of the task configuration format.
"mean" | "final" | null
default:"null"
How to derive the trial-level reward from per-step verifier results. Only applies when [[steps]] is set; leave unset for single-step tasks (defaults to “mean” on multi-step). See Multi-step tasks.
[task]
PackageInfo | null
default:"null"
Optional [task] section for registry package metadata. When present, task.name is required.
string
Package name in org/name format (e.g., “harbor/hello-world”). Required when [task] is declared.
list[Author]
default:"[]"
List of task authors. Each entry has a required name and optional email (for example,
[{ name = "Jane", email = "jane@example.com" }]).string
default:"\"\""
Human-readable description of the task.
list[string]
default:"[]"
Keywords for search and categorization.
[metadata]
object
Arbitrary metadata provided by the task author.
[verifier]
number
default:"600"
Timeout in seconds for the verifier.
"no-network" | "public" | "allowlist" | null
default:"null (no override)"
Optional override during verify(). Applied only when set and different from the verifier baseline. See Network policy.
list[string] | null
default:"null"
Allowlist hostnames when verifier.network_mode is allowlist.
object
default:"{}"
Environment variables to set when running the verifier.
string | int | null
default:"null"
Username or UID to run the verifier as. When set, the environment’s default user is configured accordingly before verification. If not set, the environment’s container default (typically root) is used.
"shared" | "separate" | null
default:"null"
Where the verifier runs. “shared” (default when no [verifier.environment] is declared) reuses the agent’s container; “separate” launches a dedicated verifier container with its own image. Omitting this field while declaring [verifier.environment] implies “separate”. Declaring “shared” alongside [verifier.environment] is a validation error.
EnvironmentConfig | null
default:"null"
Optional [verifier.environment] section (same schema as the top-level [environment]). Defines a dedicated container the verifier runs in. When set, the task’s tests/ directory becomes the verifier image’s build context — the image must provide /tests/test.sh (Linux) or /tests/test.bat (Windows) at runtime; Harbor does not upload tests for separate envs. When environment_mode=“separate” is declared without this section, a fresh copy of the top-level [environment] is used.
"no-network" | "public" | "allowlist"
default:"\"public\""
Separate verifier env baseline when [verifier.environment] is set. Same modes as environment.network_mode.
list[string] | null
default:"null"
Allowlist hostnames when verifier.environment.network_mode is allowlist.
[agent]
number | null
default:"null"
Timeout in seconds for the agent. If not set, no timeout is enforced.
"no-network" | "public" | "allowlist" | null
default:"null (no override)"
Optional override during agent.run(). Applied only when set and different from [environment]. See Network policy.
list[string] | null
default:"null"
Allowlist hostnames when agent.network_mode is allowlist.
string | int | null
default:"null"
Username or UID to run the agent as. When set, the environment’s default user is configured accordingly before agent setup and execution. If not set, the environment’s container default (typically root) is used.
[solution]
object
default:"{}"
Environment variables to set when running the solution.
[environment]
number
default:"600"
Timeout in seconds for environment build.
"no-network" | "public" | "allowlist"
default:"\"public\""
Agent env baseline. Also the shared verifier baseline when no separate verifier env overrides it. See Network policy.
list[string] | null
default:"null"
Allowlist hostnames when environment.network_mode is allowlist.
string | null
default:"null"
A pre-built Docker image to use for the environment. When set, environment/Dockerfile is optional for supported environment types.
"linux" | "windows"
default:"\"linux\""
Target operating system for the task container. “linux” (default) or “windows”. When “windows”, Harbor uses Windows-style paths, cmd.exe execution, tar-over-exec file transfer, and filters script discovery to .bat only. The Docker daemon mode and image OS are validated against this value at start; mismatches fail fast.
integer | null
default:"null"
Number of CPUs requested by the task. When omitted, Harbor leaves CPU sizing to the selected provider.
integer | null
default:"null"
Amount of RAM requested by the task in megabytes. When omitted, Harbor leaves memory sizing to the selected provider.
integer | null
default:"null"
Amount of storage requested by the task in megabytes. When omitted, Harbor leaves storage sizing to the selected provider.
integer | null
default:"null"
Number of GPUs requested by the task. When omitted, Harbor does not request GPUs.
list[string] | null
default:"null"
List of acceptable GPU types (e.g., [‘H100’, ‘A100’, ‘T4’]). None means any GPU type is acceptable.
TpuSpec | null
default:"null"
TPU slice specification (type + topology). When set, the environment requests a TPU node matching this spec; per-pod chip count is derived from the topology. Singular because a task allocates exactly one TPU slice per pod. Only supported on TPU-capable environments (currently GKE).
string
TPU accelerator type. Accepts either a user-friendly alias (e.g., ‘v6e’, ‘trillium’, ‘v4’) or a canonical GKE label (e.g., ‘tpu-v6e-slice’, ‘tpu7x’).
string
TPU topology as ‘NxM’ or ‘NxMxK’ (e.g., ‘2x4’, ‘2x2x1’). Required — GKE’s implicit default topology is not part of a stable contract, so omitting it would make Harbor runs non-reproducible across GKE versions. Per-pod TPU chip count is computed as the product of dimensions (e.g. ‘2x2x1’ → 4 chips, ‘2x4’ → 8 chips). Each dimension must be a positive integer (no leading zeros).
boolean | null
default:"null"
Deprecated compatibility field. Prefer [environment].network_mode. When set and [environment].network_mode is omitted, false maps to no-network and true maps to public.
object
default:"{}"
Environment variables required for the task, resolved from the host at runtime. Supports
${VAR} and ${VAR:-default} template syntax.string
Unique name for each MCP server entry (declare servers as [[environment.mcp_servers]] in TOML). Compatible agents register them automatically. See Environment — MCPs.
"stdio" | "sse" | "streamable-http"
default:"\"sse\""
How the agent connects to the server. “sse” and “streamable-http” require url; “stdio” requires command. Legacy value “http” is normalized to “streamable-http”.
string | null
default:"null"
Endpoint URL when transport is “sse” or “streamable-http” (e.g. http://mcp-server:8000/mcp for a Compose sidecar). Required for those transports.
string | null
default:"null"
Executable to spawn when transport is “stdio”. Required for stdio.
list[string]
default:"[]"
Arguments passed to command when transport is “stdio”.
string | null
default:"null"
Path to a skills directory in the environment. Contents are copied to the agent’s skills config directory.
HealthcheckConfig | null
default:"null"
Optional healthcheck block run after environment start (omit the whole [environment.healthcheck] section to disable). When set, command is required; other fields use the defaults below.
string
Shell command to run as a healthcheck after environment start. Exit 0 means healthy. Required when [environment.healthcheck] is present.
number
default:"5"
Time in seconds between healthcheck attempts.
number
default:"30"
Maximum time in seconds for a single healthcheck command.
number
default:"0"
Grace period in seconds after environment start during which failures don’t count.
number
default:"5"
Interval in seconds between checks during the start period.
integer
default:"3"
Number of consecutive failures before the healthcheck is considered failed.
string | null
default:"null"
Default working directory for command execution in the environment. Overrides the container WORKDIR when set.
Artifacts
list[string | ArtifactConfig]
default:"[]"
Root-level paths to snapshot from the environment into the trial artifacts directory. Single-step: collected once after verification. Multi-step: included in every step’s collection pass (step-level paths use [[steps]].artifacts — see Multi-step tasks). Each entry is a container path string or a table with source / destination / exclude.
string
Container path to download (file or directory). Required for table entries; a bare string in the artifacts list is shorthand for source only.
string | null
default:"null"
Relative path under the trial artifacts directory. When omitted, Harbor derives the host path from source.
list[string]
default:"[]"
Glob patterns to exclude when source is a directory (passed as tar —exclude flags).
Provenance
string | null
default:"null"
Optional source string for task provenance.
Multi-step configuration
The field reference above covers single-step and shared task-root settings. Multi-step tasks add[[steps]] entries with per-step agent, verifier, healthcheck, min_reward, and artifacts overrides. Step fields, workdir/setup.sh, and trial-level reward rollup are documented on multi-step tasks.
TOML templates
During task creation, you can pass a--metadata-template flag with a path to a TOML file to pre-populate task.toml with metadata fields and config defaults: