Tutorial · 20 minutes

Run it yourself

The worked examples come from one command, and it runs on a laptop. Here is how to run it on your own plan, with Python or Docker, and what you get back.

01What you need

A plan
A TaskSpec JSON file from the Studio's planner (Plan a task).
Python or Docker
Python 3.12 with uv, or Docker. A CPU is enough: no GPU, no cloud account, no key.
Some minutes
The returns tote search took 15 minutes on 4 workers: screen, combinations and finalists.

02Install

Clone the repository and install the locked dependencies with uv. The tests run on the CPU and need no network.

Terminal

$ git clone https://github.com/stray128/robot-tool-tournament.git$ cd robot-tool-tournament$ make sync$ source .venv/bin/activate# optional: the full test suite$ make test

03Run the search

Put the plan you downloaded (taskspec-<id>.json) in the repository folder and run:

Terminal

$ python -m rtt.studio.search taskspec-<id>.json --out runs/studio/my-task --pack

It screens every tool on every step it could do, combines what passed into single tools, tool changes and two-tool heads, runs the finalists through the whole task, ranks them against the best single off-the-shelf tool and writes the result. The options:

Option	Default	What it does
--out DIR	required	Where report.json and the build pack go.
--workers N	6	Simulation processes in parallel.
--conditions N	8	Placements (each with its own seed) every finalist runs the whole task on.
--screen N	3	The first N conditions each tool is screened on, step by step. At most --conditions.
--finalists N	4	Setups that go on to full-task runs.
--no-library	off	Leave out the open library's tools; catalogue and designed tools only.
--pack	off	Also write the build pack of the recommendation (or the closest setup).

Fewer conditions run faster

For a first look, --conditions 3 --finalists 2 runs in a fraction of the time. Rankings on fewer conditions are less certain; the worked examples use the defaults.

04Or run it in Docker

The simulation image has the same code and the locked dependencies, so nothing is installed on your machine. Build it once:

Terminal, in the repository folder

$ jobs/nebius/build_image.sh rtt-sim:dev# a quick check: the first gate passes in a few seconds$ docker run --rm rtt-sim:dev m1 --no-files

Then run the search with the current folder mounted at /work:

Terminal

$ docker run --rm -v "$PWD:/work" --entrypoint python rtt-sim:dev \  -m rtt.studio.search /work/taskspec-<id>.json --out /work/runs/studio/my-task --pack

The image is about 2 GB. Files it writes belong to the container's user (root); change their owner afterwards if you need to.

05What it writes

runs/studio/my-task/report.json
The whole search: the plan, every candidate and why it was ruled out, the success matrix, the combinations, the finalists, the recommendation (or the closest setup) and the timings. The command also prints the recommended setup's id.
runs/studio/my-task/build_pack/ and build_pack.zip
With --pack: the files to build the setup, and the same files zipped next to them (the returns tote pack is 10.8 kB, 7 files).
noteslicencebomcertificatemjcf

The story pages on this site are made from the same report by scripts/export_studio_web.py; see Search and ranking for every field.

06Plan live (optional)

To turn your own words into a plan, run the planner on your machine with your own Nebius Token Factory key. Anything that spends asks for a passcode you choose.

Terminal 1: the local API

$ cp .env.example .env# put your key in .env: NEBIUS_API_KEY=...$ export RTT_AGENT_PASSCODE_SHA256=$(python -c "import hashlib;print(hashlib.sha256(b'your-passcode').hexdigest())")$ rtt serve

Terminal 2: the site, pointed at it

$ cd web$ pnpm install --frozen-lockfile$ NEXT_PUBLIC_API_URL=http://127.0.0.1:8000 pnpm build$ pnpm start

Open http://127.0.0.1:4173/studio/, describe the task, enter the passcode and press Plan. A plan is one model call, or two when the first breaks a rule, on your key; the planner's guide describes the passcode and the spend caps.