Talos

Are you an AI agent? Go to the agent guide to set up and run Talos. It says which commands spend money, which ones the user must run themselves, and how to start, watch and stop a job. Once Talos is installed, talos guide prints the same guide.

Single-user autoresearch for TIG. You pick a TIG challenge and describe what to explore. An LLM then repeatedly edits the current top mainnet algorithm for that challenge, and each candidate is compiled and scored with TIG's own tig-runtime and tig-verifier on your own Modal or C3 account, or in Docker on your own machine. The run stops when a candidate beats the baseline on both training and held-out nonces, or when the budget runs out. The best candidate is written to a local, submit-ready package.

Talos never submits to TIG for you, and LLM-authored code never runs outside a container. Only the local backend runs that container on your machine, with networking off, capabilities dropped, and CPU and memory limits; the one opt-in exception is agentic codex.

Driving Talos from a coding agent? Point it at this README, or tell it: "Run talos guide and follow it."

How it works

talos run measures the current top-adoption mainnet algorithm once as the baseline. Then, until the budget runs out, it asks the LLM for an edit, compiles it on the compute backend, and scores it on training nonces. A candidate that beats the baseline on training is scored again on held-out nonces, and wins only if it still beats the baseline there. Baseline and candidates run on the same nonces, fuel and hardware class. The LLM never sees the rand_hash that seeds the nonces. docs/architecture.md has the full flowchart and the guards; docs/compute-backends.md covers the three backends.

Install

You need Linux, macOS or Windows and uv. Nothing Rust- or CUDA-related is needed locally: compiling and scoring happen on the compute backend.

uv tool install --python 3.12 'talos-tig[modal,anthropic]'
talos --version

To install the current main instead of the latest release:

uv tool install --python 3.12 'talos-tig[modal,anthropic] @ git+https://github.com/FibonAdithya/talos'

The git form was MEASURED 2026-10-27 with a local git+file:// URL ([modal] only; import modal, talos worked in the tool environment). The GitHub URL itself has not been run.

The extras are modal (the Modal backend) and anthropic (the anthropic provider). The c3 and local backends and every other provider need none. Name every extra you use in one command: MEASURED 2026-10-27, uv tool install 'talos-tig[anthropic]' over an install made with [modal] removed the Modal client. A command that needs a missing extra exits with code 2 and prints the install command. pip install 'talos-tig[modal,anthropic]' is expected to work in a virtual environment (Python 3.10 or newer), but it has not been run against a PyPI release that has the extras; pipx has not been tried. On Windows, see docs/windows.md.

Workspace

Talos keeps talos.config.json, .talos/secrets.json and runs/ in one workspace directory: the one given by talos --workspace DIR <command> or TALOS_WORKSPACE, else the nearest directory at or above the current one that holds talos.config.json, else ~/.talos/workspace. talos setup prints Workspace: <path>. In a fresh clone, talos --workspace . setup keeps everything in the clone, as before. See Workspace.

Upgrading

Upgrade with uv tool upgrade talos-tig (not yet verified against a PyPI release), then run talos deploy if you use Modal: every new version needs a redeploy, and until then talos run pauses before spending and talos doctor fails. uv records the installed extras in the tool's receipt (MEASURED 2026-10-27, uv 0.11.26, local wheel). If talos deploy or talos run still reports a missing extra, reinstall naming every extra you use, as under Install.

Try it with no accounts

talos demo runs a scripted job end to end before you create any account: no config file, no network, no credentials and no spend. It uses the real research loop with a scripted LLM and an in-process stand-in for the compute backend.

talos demo

It takes a few seconds (--delay 0 removes the pause after each line) and prints the same event stream a real run does: a compile failure and its fix, two iterations with no gain, a false positive (a candidate that wins on training and loses on the held-out nonces) and a win. It ends with:

Status: won (beat baseline on training and held-out nonces)
Best delta vs baseline: +4.000%
LLM spend: $0.00   Compute spend (estimated): $0.00
Package: .../runs/demo-<timestamp>-knapsack/package
You can find the code to submit at .../runs/demo-<timestamp>-knapsack/package/submission, fill out the template README.md to make it ready to submit to The Innovation Game!

followed by a guide to the files in the package. The demo job is written to runs/demo-<timestamp>-<challenge>/ in the workspace; delete that folder if you do not want talos status to list it.

Pick a compute backend

Timings and details per backend are in docs/compute-backends.md.

Pick an LLM provider

Only the CLI providers support agentic mode. They bill through your CLI subscription rather than per API call, so talos run asks them for an iteration budget instead of a dollar budget.

Set up and check

talos setup
talos doctor

talos setup asks for the backend, provider, model and credentials, checks each one (on Modal it also deploys the benchmark app to your account), and only then writes talos.config.json and .talos/secrets.json in the workspace. Run it again to change provider, model or backend; on Modal, talos deploy redeploys after upgrading Talos. Every prompt and check is listed under talos setup.

talos doctor spends no compute, but its provider check makes one small LLM test call. It checks the config, the LLM credential, the backend, mainnet and the dev images, and says what to fix for each failure. Then run talos doctor --full once: it compiles and scores one real mainnet algorithm on your backend, and shows the cost and asks Spend this? (default no) before it spends anything. The one measured figure is for knapsack on C3 (MEASURED 2026-09-15: £0.02 and 12 min 20 s); every other figure is labelled ESTIMATE (unverified). See talos doctor.

Your first real run

talos run --challenge knapsack \
  --direction "Try a tighter upper bound in the branch-and-bound pruning" \
  --budget-usd 20 --budget-hours 4 --budget-compute-usd 10 --yes

talos run with no flags asks for each answer instead. Before it spends anything it prints a job summary. Press Ctrl-C once to stop: Talos packages the best candidate so far, and talos run --resume <job_id> continues later. talos status lists your jobs. When the job stops, open runs/<job_id>/package/report.html in a browser to see how the search evolved (see Where results land). Watching, stopping, resuming and submitting are covered in Running a job.

What to expect

Most jobs end exhausted: a budget ran out before a candidate beat the baseline on both training and held-out nonces. An exhausted job's package is not a candidate to submit, and talos run --resume <job_id> --add-iterations N (or another --add-* flag) continues it.

Challenges

"Tested" means at least one Talos job got past its baseline on some backend. talos run warns before it starts a job on a challenge that is not tested.

Where results land

Each job writes to runs/<job_id>/ in the workspace. When it stops, runs/<job_id>/package/ holds the hand-back package: the code to submit in its submission folder, per-nonce scores.md, the hypotheses.md log, a one-page report.html and a README.md with the submission steps. You submit it yourself.

report.html shows how the search evolved over the run: a plot of every iteration's training score against the baseline, with a line from each candidate to the candidate it was edited from. Selecting a candidate shows its diff against that parent. Below the plot are per-track scores for the best candidate against the baseline, the best candidate's diff and the hypothesis log. It is one file that loads nothing from the network. talos report <job_id> writes it again from the run directory. The full layout is in Where results land.

Documentation

• docs/usage.md: every command and flag, agentic mode, results and budget.
• docs/troubleshooting.md: known failures, by the message Talos prints.
• docs/windows.md: installing and running on Windows.
• docs/maintainers.md: development, live smoke tests, dev image upgrades.
• docs/architecture.md: the research loop, its guards and the agentic sandbox.
• docs/compute-backends.md: how Modal, C3 and local Docker are used, with timings.
• docs/json-output.md: the JSON schema of talos status --json and talos show --json.

Licence

GPLv3 (see LICENSE). talos/search_replace.py is lifted from tig-foundation/prometheus-swarm (its file scripts/search_replace.py), also GPLv3; talos/agentic.py's sandbox settings mirror Prometheus's _build_sandbox_settings design without copying its code.