> ## Documentation Index
> Fetch the complete documentation index at: https://docs.harborframework.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configs

> Complete schema for configuring Harbor jobs.

Job config files provide the same controls as `harbor run` flags while supporting multiple agents, datasets, and tasks in one reusable JSON or YAML file.

```bash theme={"system"}
harbor job init --full --config-output "<config.yaml>"
harbor run --config "<config.yaml>"
```

Use `--print-config` to inspect the resolved config without running the job:

```bash theme={"system"}
harbor run --config "<config.yaml>" --print-config
```

<Note>
  All top-level fields are optional. Harbor applies the defaults shown below. Fields marked as required are required only when their containing object is present.
</Note>

## Job

<ParamField body="job_name" type="string" default="current timestamp">
  Job name. When omitted, Harbor uses the current time in `YYYY-MM-DD__HH-MM-SS` format.
</ParamField>

<ParamField body="jobs_dir" type="string" default={'"jobs"'}>
  Directory where Harbor stores job results.
</ParamField>

<ParamField body="n_attempts" type="integer" default="1">
  Number of attempts for every task and agent combination.
</ParamField>

<ParamField body="install_only" type="boolean" default="false">
  Run agent setup only, skipping the agent phase and disabling verification.
</ParamField>

<ParamField body="timeout_multiplier" type="number" default="1.0">
  Multiplier applied to task timeouts unless a phase-specific multiplier overrides it.
</ParamField>

<ParamField body="agent_timeout_multiplier" type="number | null" default="null">
  Multiplier applied to the agent execution timeout.
</ParamField>

<ParamField body="verifier_timeout_multiplier" type="number | null" default="null">
  Multiplier applied to the verifier timeout.
</ParamField>

<ParamField body="agent_setup_timeout_multiplier" type="number | null" default="null">
  Multiplier applied to the agent setup timeout.
</ParamField>

<ParamField body="environment_build_timeout_multiplier" type="number | null" default="null">
  Multiplier applied to the environment build timeout.
</ParamField>

<ParamField body="debug" type="boolean" default="false">
  Enable debug logging.
</ParamField>

<ParamField body="n_concurrent_trials" type="integer" default="4">
  Maximum number of concurrent trials. Must be at least 1. Per-agent concurrency limits cannot exceed this value.
</ParamField>

<ParamField body="quiet" type="boolean" default="false">
  Suppress individual trial progress displays.
</ParamField>

<ParamField body="retry" type="RetryConfig" default="{}">
  Retry and exponential-backoff configuration.
</ParamField>

<ParamField body="environment" type="EnvironmentConfig" default="{}">
  Shared environment-provider configuration applied to every trial.
</ParamField>

<ParamField body="verifier" type="VerifierConfig" default="{}">
  Shared verifier configuration applied to every trial.
</ParamField>

<ParamField body="metrics" type="list[MetricConfig]" default="[]">
  Job-level metrics appended to each dataset's metrics.
</ParamField>

<ParamField body="agents" type="list[AgentConfig]" default={'[{"name":"oracle"}]'}>
  Agents evaluated by the job.
</ParamField>

<ParamField body="user_agent" type="UserAgentConfig | null" default="null">
  Optional simulated-user agent and bridge applied to every trial.
</ParamField>

<ParamField body="datasets" type="list[DatasetConfig]" default="[]">
  Dataset sources expanded into tasks.
</ParamField>

<ParamField body="tasks" type="list[TaskConfig]" default="[]">
  Individual task sources.
</ParamField>

<ParamField body="artifacts" type="list[string | ArtifactConfig]" default="[]">
  Environment paths collected after each trial. A string is shorthand for an artifact with only `source` set.
</ParamField>

<ParamField body="extra_instruction_paths" type="list[string]" default="[]">
  Files appended to each task instruction, before `extra_instructions`.
</ParamField>

<ParamField body="extra_instructions" type="list[string]" default="[]">
  Inline text appended to each task instruction after `extra_instruction_paths`.
</ParamField>

<ParamField body="source_jobs" type="list[SourceJobConfig]" default="[]">
  Source jobs used for regrading. When set, Harbor derives one new trial from each matching source trial instead of expanding tasks, agents, and attempts normally.
</ParamField>

## Retry

<ParamField body="retry.max_retries" type="integer" default="0">
  Maximum retry attempts. Must be at least 0.
</ParamField>

<ParamField body="retry.include_exceptions" type="set[string] | null" default="null">
  Exception class names eligible for retries. `null` includes every exception not excluded below.
</ParamField>

<ParamField body="retry.exclude_exceptions" type="set[string] | null" default="built-in non-retryable exceptions">
  Exception class names that are never retried. Exclusions take precedence over inclusions. The defaults are `AgentTimeoutError`, `VerifierTimeoutError`, `RewardFileNotFoundError`, `RewardFileEmptyError`, `VerifierOutputParseError`, `ApiUsageLimitError`, `AgentSafetyRefusalError`, `AgentAuthenticationError`, and `ModelNotFoundError`.
</ParamField>

<ParamField body="retry.wait_multiplier" type="number" default="1.0">
  Multiplier for exponential-backoff wait times.
</ParamField>

<ParamField body="retry.min_wait_sec" type="number" default="1.0">
  Minimum delay between retries in seconds.
</ParamField>

<ParamField body="retry.max_wait_sec" type="number" default="60.0">
  Maximum delay between retries in seconds.
</ParamField>

## Agents

<ParamField body="agents[].name" type="string | null" default={'"oracle"'}>
  Pre-integrated agent name. Use `import_path` for a custom agent.
</ParamField>

<ParamField body="agents[].import_path" type="string | null" default="null">
  Custom agent import path in `module.path:ClassName` format.
</ParamField>

<ParamField body="agents[].model_name" type="string | null" default="null">
  Model identifier passed to the agent.
</ParamField>

<ParamField body="agents[].n_concurrent" type="integer | null" default="null">
  Per-agent limit on concurrent `agent.run()` phases. Must be at least 1 and cannot exceed `n_concurrent_trials`.
</ParamField>

<ParamField body="agents[].concurrency_group" type="string | null" default="null">
  Shared concurrency-pool name. Agents in the same group must set the same `n_concurrent` value.
</ParamField>

<ParamField body="agents[].skills" type="list[string]" default="[]">
  Local skill directories, Git URLs, or `org/name[@ref]` skill sources.
</ParamField>

<ParamField body="agents[].override_timeout_sec" type="number | null" default="null">
  Replace the task's agent timeout with this value in seconds.
</ParamField>

<ParamField body="agents[].override_setup_timeout_sec" type="number | null" default="null">
  Replace the agent setup timeout with this value in seconds.
</ParamField>

<ParamField body="agents[].max_timeout_sec" type="number | null" default="null">
  Upper bound for the effective agent timeout in seconds.
</ParamField>

<ParamField body="agents[].resume_trajectory" type="boolean" default="false">
  Resume the agent's native session between steps of a multi-step task. Requires agent resume support.
</ParamField>

<ParamField body="agents[].load_trajectory" type="string | null" default="null">
  Load a native `.jsonl` or ATIF `.json` trajectory before the first step. Requires the corresponding agent capability.
</ParamField>

<ParamField body="agents[].extra_allowed_hosts" type="list[string]" default="[]">
  Hostnames, IP addresses, or CIDR ranges added to the allowlist during `agent.run()` only.
</ParamField>

<ParamField body="agents[].include_logs" type="list[string]" default="[]">
  Glob patterns selecting agent log files to download.
</ParamField>

<ParamField body="agents[].exclude_logs" type="list[string]" default="[]">
  Glob patterns excluded from downloaded agent logs after applying `include_logs`.
</ParamField>

<ParamField body="agents[].kwargs" type="object" default="{}">
  Integration-specific keyword arguments passed to the agent constructor.
</ParamField>

<ParamField body="agents[].env" type="object[string, string]" default="{}">
  Environment variables exposed only during the agent phase.
</ParamField>

<ParamField body="agents[].mcp_servers" type="list[MCPServerConfig]" default="[]">
  MCP servers made available to the agent.
</ParamField>

See [pre-integrated agents](/core-concepts/agents/pre-integrated-agents), [custom agents](/core-concepts/agents/custom-agents), [skills](/core-concepts/jobs/skills), and [loading trajectories](/core-concepts/jobs/loading-trajectories).

### MCP servers

<ParamField body="agents[].mcp_servers[].name" type="string">
  Required server name.
</ParamField>

<ParamField body="agents[].mcp_servers[].transport" type={'"stdio" | "sse" | "streamable-http"'} default={'"sse"'}>
  MCP transport. The legacy value `http` is normalized to `streamable-http`.
</ParamField>

<ParamField body="agents[].mcp_servers[].url" type="string | null" default="null">
  Server URL. Required for `sse` and `streamable-http` transports.
</ParamField>

<ParamField body="agents[].mcp_servers[].command" type="string | null" default="null">
  Executable command. Required for the `stdio` transport.
</ParamField>

<ParamField body="agents[].mcp_servers[].args" type="list[string]" default="[]">
  Arguments passed to a `stdio` server command.
</ParamField>

## Simulated user

`user_agent` supports every field in `agents[]`, plus the fields below. The `bridge` field is required when `user_agent` is configured.

<ParamField body="user_agent.user_persona_path" type="string | null" default="null">
  Path to a file defining the simulated user's persona.
</ParamField>

<ParamField body="user_agent.user_prompt_template_path" type="string | null" default="null">
  Path to the Jinja2 prompt template used by the simulated user.
</ParamField>

<ParamField body="user_agent.bridge" type="BridgeConfig">
  Required bridge connecting the simulated user to the primary agent.
</ParamField>

<ParamField body="user_agent.bridge.kind" type={'"acp"'}>
  Required bridge implementation. Currently only `acp` is supported.
</ParamField>

<ParamField body="user_agent.bridge.prompt_path" type="string | null" default="null">
  Optional replacement for the bridge instructions.
</ParamField>

<ParamField body="user_agent.bridge.kwargs" type="object" default="{}">
  Bridge-specific keyword arguments.
</ParamField>

See [Simulate a user](/core-concepts/jobs/simulate-a-user).

## Environment

<ParamField body="environment.type" type="EnvironmentType | null" default={'"docker"'}>
  Pre-integrated environment provider: `docker`, `podman`, `daytona`, `e2b`, `modal`, `runloop`, `langsmith`, `ec2`, `gke`, `ack`, `openshift`, `novita`, `apple-container`, `singularity`, `islo`, `tensorlake`, `cwsandbox`, `wandb`, `use-computer`, `cua-cloud`, `blaxel`, `opensandbox`, `beam`, `skypilot`, `hf-sandbox`, `hyperbrowser`, or `vercel`. See [pre-integrated sandboxes](/core-concepts/sandboxes/pre-integrated-sandboxes).
</ParamField>

<ParamField body="environment.import_path" type="string | null" default="null">
  Custom environment import path in `module.path:ClassName` format.
</ParamField>

<ParamField body="environment.force_build" type="boolean" default="false">
  Rebuild the environment even when a cached build exists.
</ParamField>

<ParamField body="environment.delete" type="boolean" default="true">
  Delete the environment after the trial finishes.
</ParamField>

<ParamField body="environment.cpu_enforcement_policy" type={'"auto" | "limit" | "request" | "guarantee" | "ignore"'} default={'"auto"'}>
  How the provider enforces the task's CPU value.
</ParamField>

<ParamField body="environment.memory_enforcement_policy" type={'"auto" | "limit" | "request" | "guarantee" | "ignore"'} default={'"auto"'}>
  How the provider enforces the task's memory value.
</ParamField>

<ParamField body="environment.override_cpus" type="integer | null" default="null">
  Replace the task's CPU value at runtime.
</ParamField>

<ParamField body="environment.override_memory_mb" type="integer | null" default="null">
  Replace the task's memory value in MB.
</ParamField>

<ParamField body="environment.override_storage_mb" type="integer | null" default="null">
  Replace the task's storage value in MB.
</ParamField>

<ParamField body="environment.override_gpus" type="integer | null" default="null">
  Replace the task's GPU count.
</ParamField>

<ParamField body="environment.override_tpu" type="TpuSpec | null" default="null">
  Replace the task's TPU specification.
</ParamField>

<ParamField body="environment.suppress_override_warnings" type="boolean" default="false">
  Deprecated. This field is accepted but has no effect and is excluded when serializing configs.
</ParamField>

<ParamField body="environment.mounts" type="list[ServiceVolumeConfig] | null" default="null">
  Docker Compose long-syntax volume mounts applied to the environment container.
</ParamField>

<ParamField body="environment.extra_docker_compose" type="list[string]" default="[]">
  Additional Docker Compose overlay files.
</ParamField>

<ParamField body="environment.env" type="object[string, string]" default="{}">
  Baseline environment variables exposed inside the sandbox.
</ParamField>

<ParamField body="environment.kwargs" type="object" default="{}">
  Provider-specific keyword arguments passed to the environment constructor.
</ParamField>

<ParamField body="environment.extra_allowed_hosts" type="list[string]" default="[]">
  Hostnames, IP addresses, or CIDR ranges added to the environment network baseline.
</ParamField>

See [resources](/core-concepts/tasks/resources), [network policies](/core-concepts/tasks/network-policies), and [custom sandboxes](/core-concepts/sandboxes/custom-sandboxes).

### TPU override

<ParamField body="environment.override_tpu.type" type="string">
  Required TPU alias or canonical GKE accelerator label, such as `v6e` or `tpu-v6e-slice`.
</ParamField>

<ParamField body="environment.override_tpu.topology" type="string">
  Required topology in `NxM` or `NxMxK` format, such as `2x4`.
</ParamField>

### Mounts

<ParamField body="environment.mounts[].type" type={'"bind" | "volume" | "image"'}>
  Required mount type.
</ParamField>

<ParamField body="environment.mounts[].source" type="string">
  Required host path, named volume, or image source.
</ParamField>

<ParamField body="environment.mounts[].target" type="string">
  Required target path inside the container.
</ParamField>

<ParamField body="environment.mounts[].read_only" type="true" default="omitted">
  Set to `true` for a read-only mount.
</ParamField>

<ParamField body="environment.mounts[].bind.create_host_path" type="false" default="omitted">
  Set to `false` to prevent Docker Compose from creating a missing bind source path.
</ParamField>

<ParamField body="environment.mounts[].bind.selinux" type={'"z" | "Z"'} default="omitted">
  Optional SELinux relabeling mode for a bind mount.
</ParamField>

<ParamField body="environment.mounts[].volume.subpath" type="string" default="omitted">
  Optional subpath within a named volume.
</ParamField>

<ParamField body="environment.mounts[].image.subpath" type="string" default="omitted">
  Optional subpath within an image mount.
</ParamField>

## Verifier

<ParamField body="verifier.override_timeout_sec" type="number | null" default="null">
  Replace the task's verifier timeout with this value in seconds.
</ParamField>

<ParamField body="verifier.max_timeout_sec" type="number | null" default="null">
  Upper bound for the effective verifier timeout in seconds.
</ParamField>

<ParamField body="verifier.include_logs" type="list[string]" default="[]">
  Glob patterns selecting verifier log files to download. The reward file is always downloaded.
</ParamField>

<ParamField body="verifier.exclude_logs" type="list[string]" default="[]">
  Glob patterns excluded from verifier logs after applying `include_logs`.
</ParamField>

<ParamField body="verifier.env" type="object[string, string]" default="{}">
  Environment variables exposed only during the verifier phase.
</ParamField>

<ParamField body="verifier.import_path" type="string | null" default="null">
  Custom verifier import path in `module.path:ClassName` format.
</ParamField>

<ParamField body="verifier.kwargs" type="object" default="{}">
  Keyword arguments passed to the custom verifier.
</ParamField>

<ParamField body="verifier.disable" type="boolean" default="false">
  Skip verification. Automatically set to `true` when `install_only` is enabled.
</ParamField>

See [custom verifiers](/core-concepts/jobs/custom-verifiers) and [environment variables](/core-concepts/jobs/environment-variables).

## Datasets

<ParamField body="datasets[].path" type="string | null" default="null">
  Local dataset directory. With `repo`, this selects a repo-relative implicit dataset directory.
</ParamField>

<ParamField body="datasets[].name" type="string | null" default="null">
  Harbor Hub dataset in `org/name` format, or a bare dataset name for a custom or Git-repository registry.
</ParamField>

<ParamField body="datasets[].version" type="string | null" default="null">
  Version selected from a JSON registry or a named Git-repository registry.
</ParamField>

<ParamField body="datasets[].ref" type="string | null" default="null">
  Tag, revision, or digest selected for a Harbor Hub dataset.
</ParamField>

<ParamField body="datasets[].registry_url" type="string | null" default="null">
  URL of a custom `registry.json` file.
</ParamField>

<ParamField body="datasets[].registry_path" type="string | null" default="null">
  Path to a custom `registry.json`. With `repo`, this path is relative to the repository.
</ParamField>

<ParamField body="datasets[].repo" type="string | null" default="null">
  Git repository shorthand or URL, optionally pinned with `@ref`.
</ParamField>

<ParamField body="datasets[].overwrite" type="boolean" default="false">
  Overwrite cached remote tasks.
</ParamField>

<ParamField body="datasets[].download_dir" type="string | null" default="null">
  Directory used to cache downloaded tasks.
</ParamField>

<ParamField body="datasets[].task_names" type="list[string] | null" default="null">
  Glob patterns selecting tasks by name.
</ParamField>

<ParamField body="datasets[].exclude_task_names" type="list[string] | null" default="null">
  Glob patterns excluding tasks after applying `task_names`.
</ParamField>

<ParamField body="datasets[].n_tasks" type="integer | null" default="null">
  Maximum number of tasks after inclusion and exclusion filters are applied.
</ParamField>

Each dataset must select exactly one source shape. Without `repo`, set either `path` or `name`, but not both. With `repo`, `path` selects an implicit dataset while `name` selects a named registry dataset. `version` and `ref` cannot both be set.

See [datasets](/core-concepts/datasets/datasets), [custom registries](/core-concepts/datasets/registries), and [Git repository datasets](/core-concepts/datasets/git-repos).

## Tasks

<ParamField body="tasks[].path" type="string | null" default="null">
  Local task directory, or the path within a Git repository when `git_url` is set.
</ParamField>

<ParamField body="tasks[].git_url" type="string | null" default="null">
  Git repository containing the task.
</ParamField>

<ParamField body="tasks[].git_commit_id" type="string | null" default="null">
  Git commit containing the task. Requires `git_url`.
</ParamField>

<ParamField body="tasks[].name" type="string | null" default="null">
  Harbor Hub task name in `org/name` format.
</ParamField>

<ParamField body="tasks[].ref" type="string | null" default="null">
  Harbor Hub task tag, revision, or digest. Requires `name`.
</ParamField>

<ParamField body="tasks[].overwrite" type="boolean" default="false">
  Overwrite the cached remote task.
</ParamField>

<ParamField body="tasks[].download_dir" type="string | null" default="null">
  Directory used to cache the downloaded task.
</ParamField>

<ParamField body="tasks[].source" type="string | null" default="null">
  Optional source label used when grouping tasks and metrics.
</ParamField>

Every task must set either `path` or `name`, but not both. A Git task uses `path` with `git_url`; a Harbor Hub task uses `name` with an optional `ref`.

See the [task overview](/core-concepts/tasks/overview).

## Metrics

<ParamField body="metrics[].type" type={'"sum" | "min" | "max" | "mean" | "uv-script"'} default={'"mean"'}>
  Metric implementation used to aggregate task rewards.
</ParamField>

<ParamField body="metrics[].kwargs" type="object" default="{}">
  Keyword arguments passed to the metric implementation. `uv-script` requires `script_path`.
</ParamField>

See [Metrics](/core-concepts/datasets/metrics).

## Artifacts

<ParamField body="artifacts[].source" type="string">
  Required environment path to collect. It cannot contain `..` path components.
</ParamField>

<ParamField body="artifacts[].destination" type="string | null" default="null">
  Optional path under the trial's artifact directory. Harbor derives it from `source` when omitted.
</ParamField>

<ParamField body="artifacts[].exclude" type="list[string]" default="[]">
  Patterns excluded when downloading a directory artifact.
</ParamField>

<ParamField body="artifacts[].service" type="string | null" default="null">
  Docker Compose service to collect from. `null` and `main` target the agent container.
</ParamField>

See [artifact collection](/core-concepts/jobs/artifact-collection).

## Regrade sources

<ParamField body="source_jobs[].action" type={'"regrade"'}>
  Required derivation action. Currently only `regrade` is supported.
</ParamField>

<ParamField body="source_jobs[].type" type={'"local" | "hub"'}>
  Required source location.
</ParamField>

<ParamField body="source_jobs[].job_id" type="string | null" default="null">
  Source job UUID. Required for a Hub source and optional for a local source.
</ParamField>

<ParamField body="source_jobs[].path" type="string | null" default="null">
  Source job directory. Required for a local source and invalid for a Hub source.
</ParamField>

Regrading cannot be combined with `install_only`. See [Regrade a job](/core-concepts/jobs/regrade).