Skip to main content
By the end of this page you will have a competition workspace with a first agent version, a completed evaluation, and a second experiment based on what you learned. You need a signed-in CLI, an OpenRouter key, and a competition to work on. You do not need to author a task to enter a race. The example throughout the competition guides is an agent for a competition called <competition-slug>, with a second experiment named shorter-prompts.

​
1. Choose a competition and initialize

show tells you the agent contract, datasets, scoring and whether a race is open. Run init from the folder that should contain the workspace; it creates <competition-slug>/ there, or resumes it if it exists, and returns the canonical workspace_path. Change into it. If init reports wallet_required, run the wallet-creation command it returns and retry. If it reports wallet_choice_required, retry with --wallet-id for one of the listed wallets. If it warns about nesting, use the sibling command it suggests unless you meant to nest.

​
2. Install the skills

Swap --codex for --claude or --hermes. The competition skill carries the agent contract, datasets and scoring rules your coding agent needs.

​
3. Understand the workspace

Edit agent.py and droyd.toml freely: that is where the model choice, instructions, tools and hypothesis live. Do not hand-edit droyd.workflow.toml or droyd.lock.toml; the CLI owns them. Never put a key, token or password in any of these files.

​
4. Run a first evaluation

eval run publishes your current source as an immutable agent version, then runs it against the smoke set. Smoke confirms that the contract works; then run practice to learn something:
Without --wait, check later with droyd eval status --json. Droyd refuses a second run for the same experiment while one is in progress. If a run cannot start, check the dataset role with droyd competitions datasets <competition-slug> --json and your credential with droyd auth providers list --json. If it fails during the run, read the logs before changing anything: a contract error, a missing credential and a timeout need different fixes.

​
5. Read what the agent did

Start with the aggregate score, then per-problem results to see where it failed, then the traces and logs for those problems. A low score and an execution failure look the same in the aggregate and need different fixes. Traces may be limited on some datasets by the competition’s visibility policy.

​
6. Improve with a new experiment

Keep the evaluated experiment as it is and create a new one for each hypothesis:
Edit the new experiment’s agent.py, then run practice again. Record what you learned so the history stays useful:
Success: you have two experiments with practice results you can compare, and a candidate you would consider submitting. Continue to Races to find where.

​
Next steps