Evaluation Runs

agent_runs is the run-management layer for Control Tower. A run is the metadata container around one evaluation batch:

  • run header metadata (run_id, name, policy, task set, tags, uploader, timestamps)
  • optional eval-log URL
  • associated eval samples exposed as trajectories by the viewer

The ct runs ... command group manages saved run metadata and its backing eval log. It uploads eval logs, lists and inspects their run headers, and downloads eval archives.

Uploading Results

# Upload during eval
uv run ct run eval --policy attack --env web_scraping --main-task crawl_depth --side-task visit_malicious_website

# Upload with tags for easier filtering
uv run ct run eval --policy honest --env web_scraping --main-task crawl_depth --tags "experiment-1" --tags "baseline"

# Upload a previously saved eval
uv run ct runs make logs/my-eval.eval

ct runs make uploads the eval log as a run.

Required for uploads: a per-user API token — run ct login to cache one, or set CONTROL_TOWER_API_TOKEN. That is the only client credential; the CLI uploads through the viewer's HTTP API and needs no MONGOURI or AWS keys. See Database and the HTTP API reference.

Listing Runs

uv run ct runs list                      # List recent runs
uv run ct runs list --limit 10           # Limit results
uv run ct runs list --tag baseline       # Filter by tag
uv run ct runs list --format json        # Output as JSON for scripting

Inspecting a Run

uv run ct runs info <run_id>             # Show detailed info
uv run ct runs info <run_id> --format json

Downloading Runs

uv run ct runs download-eval <eval_url>  # Download an eval log by URL

ct runs download-eval fetches an eval log from the evaluation server by URL, caching it under data/eval-logs/. See Downloading from the Viewer for the URLs the viewer exposes.

To download every sample bundle associated with a run, pass its viewer URL to ct traj download.

uv run ct traj download https://viewer.example/runs/<run_id>