Configuring experiments

​

Configuration

​

Field reference

​

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

• 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 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.
  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.
• additional_context (list of strings, default: [])
  Additional files to include as context. Same syntax as target_code.

​

File list syntax

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

• 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

• 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:
  envs:
    - name: DATABASE_URL
      value: postgres://localhost/mydb
  
• services (list)
  Sidecar services to run alongside the sandbox. See sandbox.services 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[]

• 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

• 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.
  ideas:
    - "Try batching database writes"
    - "Consider async I/O for network calls"
  

​

Full example

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