Control Tower v6 is available. See the changelog for breaking changes.

Control Tower

User Guide · Building Environments

The hawk-values contract

Every env that runs on hawk (ct run eval --hawk) carries a hand-authored hawk-values.yaml in codebase/, alongside its Dockerfile and compose.yml:

<env-repo>/
  codebase/
    Dockerfile          # shared with local-docker evals
    compose.yml         # drives local-docker evals
    hawk-values.yaml    # hand-authored K8sSandboxEnvironmentValues; drives the hawk path
  main_tasks/
  side_tasks/

A hawk-values file translates the compose file beside it, and its name is the compose file's with compose replaced by hawk-values: compose.yml is translated by hawk-values.yaml, and an env whose args pick compose.tinker.yml needs a hawk-values.tinker.yaml to run that variant on Hawk (only the first compose is replaced, so docker-compose.yml is translated by docker-hawk-values.yaml).

Control Tower copies each environment entry of the compose file that reads a setting variable onto the service of the same name here, resolved from the setting's values file. An entry that also reads COMPOSE_PROJECT_NAME, ENV_IMAGE_REPO_<ENV> or ENV_IMAGE_TAG_<ENV> arrives with those reads unresolved, so keep them in entries of their own.

This file is the contract between env authors and Control Tower. Control Tower substitutes the placeholders listed under Substitution rules and passes everything else verbatim to the Hawk Kubernetes (K8s) sandbox chart (inspect_k8s_sandbox).

Required header

Every hawk-values.yaml starts with:

# hawk-values for <env_id> — see docs/hawk-values-contract.md for the contract. # CT substitutes ${CT_IMAGE_REGISTRY_PREFIX} and ${HAWK_ENV_TAG} at submission time.

Image tags

Each env's images are tagged with that env's commit SHA: the operator publishes at the SHA of the env's .settings/ checkout (see "Env-image registry" in ops/docs/hawk-deployment.md), and ct run eval --hawk resolves ${HAWK_ENV_TAG} to the same SHA. Setting CONTROL_TOWER_HAWK_ENV_TAG in .env pins every env in a run to that one tag.

The shared internet-simulator image is published under the src-<hash> tag Control Tower computes over the simulator's source, which CI pushes whenever that source reaches main. ct run eval --hawk runs the simulator at the tag of the Control Tower commit the runner installs, so the simulator server always speaks the registration protocol that runner sends. A branch that changes the simulator's source runs on Hawk once its tag is published: dispatch the publish workflow on the branch (gh workflow run publish-internet-simulator-image.yml --ref <branch>).

Substitution rules

PlaceholderResolved fromWhen
${CT_IMAGE_REGISTRY_PREFIX}CONTROL_TOWER_IMAGE_REGISTRY_PREFIX in the user's .env (passed via eval-set YAML to runner pod)Runner-task-start, before K8sSandboxEnvironmentConfig(values=Path(...)) is constructed
${HAWK_ENV_TAG}The env's commit SHA (see Image tags); CONTROL_TOWER_HAWK_ENV_TAG in .env overridesSame
${HAWK_TASK_IMAGES}The Hawk deployment's protected task image registry, which Hawk sets in the runner's environmentSame

Every other ${...} token is passed through verbatim. Control Tower writes the substituted file, and each values file it derives from it, to its own cache directory and points the sandbox spec there; it never writes into the env checkout.

Image reference convention

  • Control Tower-built environment images: ${CT_IMAGE_REGISTRY_PREFIX}/env-<envname>:${HAWK_ENV_TAG}
  • A private env's images: ${HAWK_TASK_IMAGES}/github.com/<owner>/<repo>:<compose service>-${HAWK_ENV_TAG} (see Private env images)
  • Internet-simulator: ${CT_IMAGE_REGISTRY_PREFIX}/env-internet-simulator:src-<hash>, which Control Tower writes itself (see Internet-simulator pattern); a values file never names it.
  • Third-party images (postgres, redis, nginx, etc.): literal pull strings with no substitution, which must be anonymously pullable from public Docker Hub or present in the operator's registry.

Worked example: clinical_trial

Local-docker shape (codebase/compose.yml):

services: default: image: linuxarena/env-clinical_trial:${ENV_IMAGE_TAG_CLINICAL_TRIAL:-latest} build: ... depends_on: postgres: condition: service_healthy volumes: - ./init/db/init.sql:/docker-entrypoint-initdb.d/init.sql:ro postgres: image: postgres:16.12 environment: POSTGRES_DB: vaccine_trial POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres

K8s shape (hawk-values.yaml):

# hawk-values for clinical_trial — see docs/hawk-values-contract.md for the contract. # CT substitutes ${CT_IMAGE_REGISTRY_PREFIX} and ${HAWK_ENV_TAG} at submission time. services: default: image: ${CT_IMAGE_REGISTRY_PREFIX}/env-clinical_trial:${HAWK_ENV_TAG} command: - /bin/bash - -c - /app/restart.sh && exec tail -f /dev/null readinessProbe: exec: command: [sh, -c, "pg_isready -h postgres -U postgres"] initialDelaySeconds: 5 periodSeconds: 2 postgres: image: postgres:16.12 env: - { name: POSTGRES_DB, value: vaccine_trial } - { name: POSTGRES_USER, value: postgres } - { name: POSTGRES_PASSWORD, value: postgres } - { name: INIT_SQL_B64, value: <base64-encoded-init.sql> } command: - /bin/sh - -c - printf %s "$INIT_SQL_B64" | base64 -d > /docker-entrypoint-initdb.d/init.sql && exec docker-entrypoint.sh postgres readinessProbe: exec: command: [sh, -c, "pg_isready -U postgres"]

K8s has no depends_on, so default runs its startup in the foreground and execs the idle process only once it succeeds: a startup that fails because a dependency is not up yet exits the container, and the kubelet restarts it. Starting it in the background (&) leaves the container idle with nothing running when it fails, and the sample waits out the Helm timeout.

Both files coexist in codebase/. compose.yml drives local-docker evals; hawk-values.yaml drives the hawk path.

Do not declare additionalResources with fixed names. Every sample in an eval-set is its own Helm release in a shared namespace, so a resource with a hardcoded metadata.name, such as a ConfigMap, collides across concurrent releases and the second sample fails with a Helm ownership conflict (invalid ownership metadata; ... release-name must equal). The chart runs additionalResources through tpl, so {{ .Release.Name }}-scoped names render, but services.*.volumes entries are not templated, so a release-scoped ConfigMap cannot be mounted. Instead, bake file content into the env image or carry it as a base64 env var that the service command writes out (as INIT_SQL_B64 above). Hawk 4.1.0 and later refuse any additionalResources a task supplies.

Private env images

Control Tower attaches no pull credential on Hawk, so an image a sandbox pulls is either public or one of the deployment's protected task images. A private env uses the second: its repo's CI publishes to the Hawk repository <registry>/<env>-tasks/github.com/<owner>/<repo>, and Hawk lets a run pull from it only when the run uses that repo's code and the submitter's code groups cover it.

Hawk keeps one repository per GitHub repo, so an env with several images tells them apart by tag:

services: default: image: ${HAWK_TASK_IMAGES}/github.com/linuxarena/load_balancer:default-${HAWK_ENV_TAG} backend: image: ${HAWK_TASK_IMAGES}/github.com/linuxarena/load_balancer:backend-${HAWK_ENV_TAG}

A values file that names ${HAWK_TASK_IMAGES} is refused on a deployment with protected task images off. A run can pull from at most 20 protected repositories, so an eval set over more private envs than that is split.

The env repo publishes with the reusable publish-hawk-task-images.yml, as a job after its Docker Hub build:

jobs: build: uses: linuxarena/control-tower/.github/workflows/build-env-images.yml@main # ... hawk: needs: build permissions: contents: read id-token: write uses: linuxarena/control-tower/.github/workflows/publish-hawk-task-images.yml@main secrets: DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}

It copies each image the build pushed to Docker Hub at the commit SHA into the protected repository as <compose service>-<commit SHA>, so both registries hold the same image. The deployment comes from four Actions variables, set once for the organization from the Hawk stack's outputs: HAWK_TASK_IMAGE_REQUESTER_ROLE, HAWK_TASK_IMAGE_BROKER, HAWK_TASK_IMAGE_AUDIENCE and HAWK_TASK_IMAGE_AWS_REGION.

Protected tags never move, so a private env has no latest on Hawk: leave CONTROL_TOWER_HAWK_ENV_TAG unset, which runs each env at its commit. Hawk publishes only from push, workflow_dispatch and schedule runs on main, so the release workflow, which runs on a merged pull request, publishes no version tag there.

Internet-simulator pattern

An env that declares internet_simulator gets the simulator on Hawk as it does on Docker: Control Tower adds the internet-simulator service to the sample's values at task start, and the env's hawk-values.yaml declares none. A values file that declares an internet-simulator service is refused before any sample starts, whether or not the env declares internet_simulator. An env that declares no internet_simulator gets no simulator pod.

The service Control Tower adds runs the simulator image at its src-<hash> tag with no securityContext and the chart's default resources, carries the registration of its personas, upstream proxies and the sample's services as participants, and lists the persona hostnames as additionalDnsRecords. Control Tower also sets dnsRecord: true on every other service, so the simulator can resolve each by name and attribute its requests. When the values file declares networks, the simulator joins the one named by the config's network, with underscores written as hyphens (tickets_network joins tickets-network); a values file whose networks include no such name is refused.

The env's own services still wire their side by hand:

services: default: # ... env vars to talk to IS, agent-side startup wrapping ... env: - { name: IS_BASE_URL, value: "http://internet-simulator" } - { name: LB_PERSONA_HOSTS, value: "filebin.net packages-cdn.com" } command: - /bin/bash - -c - | # Wait for IS, write /etc/hosts overrides, register personas, then run env startup until curl -sf "$IS_BASE_URL/health"; do sleep 1; done IS_IP=$(getent hosts internet-simulator | awk '{print $1}') for h in $LB_PERSONA_HOSTS; do echo "$IS_IP $h" >> /etc/hosts; done curl -sfX POST "$IS_BASE_URL/personas" -H 'Content-Type: application/json' -d '...' /app/restart.sh && exec tail -f /dev/null

Each sample gets its own internet-simulator pod.

Submitted scripts are not isolated on Hawk. run_in_internet_simulator runs each one as root inside the sample's simulator pod, so the script can read the pod's own environment through /proc/1/environ (including any upstream API key Control Tower injects), the CA private key under /app/ca, and the simulator's loopback /_internal API, which reads and clears the sample's logs. Under Docker each script runs in its own container with none of these.

The chart's coredns sidecar owns port 53 in every pod and serves persona names from additionalDnsRecords.

Validation

Run both checks:

  1. Local helm template (every env author runs locally before merging; env-repo CI runs the same):

    helm template test-release <chart-path> \ --set CT_IMAGE_REGISTRY_PREFIX=example.invalid \ --set HAWK_ENV_TAG=test \ -f hawk-values.yaml

    It must exit 0; this catches typos, indentation bugs, and dangling placeholders. The chart is bundled with inspect_k8s_sandbox at .venv/lib/python*/site-packages/k8s_sandbox/resources/helm/agent-env/.

  2. End-to-end smoke (after the env's images are published):

    ct run eval --hawk -e <env> -t <one-cheap-main-task> \ --policy honest --model-role untrusted=anthropic/claude-sonnet-4-6 \ --protocol null-blue-team -wa max_steps=10 \ --eval-arg time_limit=600

    A new env is done when this writes a local .eval file with status success.

Network isolation

Hawk runs samples in its native Kubernetes sandbox and rejects EC2, replay, simulated, external-sandbox, and simulator-disabled settings in the submitted task configuration.

ct run eval --hawk --no-internet clears the chart's allowDomains, allowDomainsPorts, allowCIDR, and allowEntities grants. The chart's Cilium policy still allows communication within the sample and DNS for its services, while denying direct external egress from every sample service. The sandbox configuration is carried in the Hawk task payload and recorded with the run.

Simulator personas and exposed services remain reachable within the sample. Before the agent's first action, Control Tower moves the env's seed_assets_from files into the simulator pod and installs the simulator's CA in every other pod, as it does on Docker. With --no-internet, Hawk's runner rejects environments that declare upstream API proxies before simulator injection, because the chart does not set up the agent-only hostname aliases and CA trust those proxies need. Run such environments on Docker.

This requires the supported inspect_k8s_sandbox chart and a Cilium cluster enforcing its CiliumNetworkPolicy resources. The chart always creates Cilium policies, so a cluster without that CRD fails installation. Restricted additionalResources accepts only core-v1 Secrets and ConfigMaps, excluding service-account tokens; template substitutions are limited to {{ .Release.Name }} and {{ .Release.Namespace }}. Workloads, policy resources, and executable Helm templates are rejected. With internet access enabled, the environment's authored chart grants apply.