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

# Configuring experiments

> Complete reference for the Hive experiment configuration file.

## Configuration

Experiment configuration lives in a `hive.yaml` file that you pass explicitly to `hive create exp -c hive.yaml`.

## Field reference

Below, we document the fields that can be specified in a configuration YAML.

### Top level fields

* **`apiversion`** (string, default: `v1alpha1`)\
  Configuration schema version.

* **`experiment_name`** (string, required)\
  Name of the experiment. Must be a valid DNS label (`[a-z0-9-]`, max 63 characters, no leading `-`). If it ends with `-`, a random suffix is appended for uniqueness.

* **`coordinator_config_name`** (string, default: `default-coordinator-config`)\
  Coordinator config to use for the experiment.

***

### `repo`

Repository configuration for the experiment source code.

* **`source`** (string)\
  Where the experiment source code comes from. Can be:

  * A remote git URL — `https://`, `ssh://`, or `git@`.
  * A local directory path (absolute or relative; `~` and environment variables are expanded). The directory is uploaded directly, so you can run experiments on uncommitted local changes.

  If omitted (`null`), no source is uploaded — the [base image](/gettingstarted/custom-base-image) must already contain the code at the sandbox `workdir`.

* **`files`** (list of strings, default: `[]`)\
  Files and directories to include from `source`. An empty list includes everything. Patterns are applied in order; prefix an entry with `!` to exclude. Globs (`*`, `?`, `[…]`) are supported. Hidden files and symlinks are skipped.

  ```yaml theme={null}
  repo:
    files:
      - src              # include the src directory
      - "*.py"           # include top-level Python files
      - "!src/secrets"   # exclude a subdirectory
  ```

* **`branch`** (string, default: `main`)\
  Branch to use when cloning a remote source.

* **`evaluation_script`** (string, default: `evaluation.py`)\
  Script that evaluates experiment results (path relative to repo root).

* **`target_code`** (list of strings, required)\
  Code for agents to evolve. Must be a YAML list — see [file list syntax](#file-list-syntax).

* **`additional_context`** (list of strings, default: `[]`)\
  Additional files to include as context. Same syntax as `target_code`.

<Note>
  The clone happens client-side. For private repos, consider using SSH (e.g.
  `git@github.com:<org>/<repo>.git`).
</Note>

#### File list syntax

The `target_code` and `additional_context` fields must be YAML lists. Each entry is a file path with an optional line range:

```yaml theme={null}
target_code:
  - main.py               # entire file
  - main.py:1-50          # lines 1 to 50
  - main.py:1-10&21-30    # multiple ranges
  - evolve.py             # another file
```

***

### `runtime`

Controls experiment execution.

* **`num_agents`** (integer, default: `1`)\
  Number of parallel agents to run.

* **`max_runtime_seconds`** (integer, default: `-1`)\
  Maximum execution time in seconds. `-1` = unlimited.

* **`max_iterations`** (integer, default: `-1`)\
  Maximum iterations per agent. `-1` = unlimited.

* **`stochastic_evaluator`** (boolean, default: `false`)\
  Whether the evaluator is stochastic. When `true`, the Hive accounts for evaluation noise by re-evaluating high-variance candidates so fitnesses can be compared reliably.

***

### `sandbox`

Container environment configuration.

* **`base_image`** (string, required)\
  Docker base image (e.g. `python:3.14-slim`).

* **`workdir`** (string, default: `/app`)\
  Working directory inside the container.

* **`setup_script`** (string, default: `null`)\
  Shell script to run before the experiment starts (e.g. install dependencies). Omit or set to `null` if no setup is needed.

* **`evaluation_timeout`** (integer, default: `60`)\
  Maximum time (seconds) for the evaluation script to run.

* **`envs`** (list)\
  Environment variables to set in the container. Each entry has a `name` and `value`:

  ```yaml theme={null}
  envs:
    - name: DATABASE_URL
      value: postgres://localhost/mydb
  ```

* **`services`** (list)\
  Sidecar services to run alongside the sandbox. See [`sandbox.services`](#sandboxservices) below.

#### `sandbox.resources`

* **`cpu`** (string, default: `"1"`)\
  CPU limit (e.g. `"2"`, `"500m"`).

* **`memory`** (string, default: `"2Gi"`)\
  Memory limit (e.g. `"4Gi"`, `"512Mi"`).

* **`accelerators`** (string)\
  GPU resources (e.g. `a100-80gb:8`).

* **`shmsize`** (string)\
  Size of `/dev/shm` (e.g. `"1Gi"`).

#### `sandbox.services[]`

Each entry defines a sidecar container that runs alongside the sandbox.

* **`name`** (string, required)\
  Service name.

* **`image`** (string, required)\
  Docker image for the service.

* **`ports`** (list)\
  Ports to expose. Each entry has a `port` (integer) and optional `protocol` (`TCP` or `UDP`, defaults to `TCP`).

* **`envs`** (list)\
  Environment variables (same format as `sandbox.envs`).

* **`command`** (list of strings)\
  Container entrypoint override.

* **`args`** (list of strings)\
  Arguments to the entrypoint.

* **`resources.cpu`** (string, default: `"1"`)\
  CPU limit for this service.

* **`resources.memory`** (string, default: `"2Gi"`)\
  Memory limit for this service.

***

### `prompt`

Optional prompt configuration for the Hive agents. Omit this section entirely to use defaults.

* **`enable_evolution`** (boolean, default: `false`)\
  Whether to enable evolution for the experiment.

* **`context`** (string)\
  Experiment-specific context to provide to agents.

* **`ideas`** (list of strings)\
  Ideas that will be randomly sampled and injected into the Hive.

  ```yaml theme={null}
  ideas:
    - "Try batching database writes"
    - "Consider async I/O for network calls"
  ```

***

## Full example

```yaml title="hive.yaml" theme={null}
apiversion: v1alpha1
experiment_name: my-experiment-
coordinator_config_name: default-coordinator-config

repo:
  source: https://github.com/your-org/your-repo.git
  branch: main
  evaluation_script: evaluation.py
  target_code:
    - main.py:1-50
  additional_context:
    - utils.py:10-30

runtime:
  num_agents: 10
  max_runtime_seconds: 3600
  max_iterations: 100
  stochastic_evaluator: false

sandbox:
  base_image: python:3.14-slim
  workdir: /app
  evaluation_timeout: 60
  setup_script: |
    pip install -r requirements.txt
    python setup.py
  resources:
    cpu: "2"
    memory: "4Gi"
    shmsize: "1Gi"
    accelerators: a100-80gb:8
  envs:
    - name: DATABASE_URL
      value: postgres://localhost/mydb
    - name: DEBUG
      value: "true"
  services:
    - name: redis
      image: redis:7-alpine
      ports:
        - port: 6379
          protocol: TCP
      resources:
        cpu: "500m"
        memory: "512Mi"
    - name: worker
      image: my-worker:latest
      command: ["python"]
      args: ["-m", "worker", "--queue", "default"]
      envs:
        - name: WORKER_CONCURRENCY
          value: "4"
      resources:
        cpu: "1"
        memory: "1Gi"

prompt:
  enable_evolution: true
  context: "Focus on optimizing the data pipeline for throughput"
  ideas:
    - "Try batching database writes"
    - "Consider async I/O for network calls"
    - "Explore caching intermediate results"
```

## Next steps

<CardGroup cols={1}>
  <Card title="Managing experiments" icon="flask-conical" href="/gettingstarted/cli/experiments">
    Create, monitor, and manage your Hive experiments.
  </Card>
</CardGroup>