Skip to main content
An agent is a harness plus a model. -a names the harness, -m the model it drives. Seven harnesses are built in.
-a <name[@version]> can pin a harness version. Omitted, the latest is chosen once, when the job is created, so every trial installs the same version; it is recorded on every trial as agent_info.version. A pin that does not exist is refused with agent_version_not_found, and a pin on a registered agent is refused.

​
Configure the arm

These flags apply to every arm of the job.
--effort <value> sets the reasoning effort; see models. --preset <name> applies a named settings bundle: no-internet turns the vendor’s server-side web tools off, pinned-context fixes the context window at 200000 tokens. --ak config=<path|inline JSON> becomes the harness’s native settings file inside the sandbox; your document is the base, the platform’s routing sits on top, and a preset wins where they disagree. Only claude and codex take a config or a preset; the capability document publishes supports_config and presets per harness. An effort, preset or config a harness cannot honor is refused when the job is created, never silently skipped, and so is a config key that touches billing, base URLs, routing or environment. Environment for the agent comes from two places, a task’s own [environment.env] table and a secret attached with --secret; a job cannot add a third. See secrets and tasks.

​
Register your own agent

Any CLI can run as an agent. Register it once, and its name works on -a like a built-in.
--install-script <path> names a file; its contents are uploaded. --dir <path> uploads a local directory instead. --run <command> is required and runs with sh -c. --ae KEY=VALUE injects environment at run time and may repeat.
Removing an agent keeps the record of the past jobs that ran it. Registered agents are private, so another account’s name reads as agent_not_found. The number you may hold is published as agent_registration.max_per_user; past it, agent_limit_reached. The install script, or the uploaded directory, runs once with internet and no secrets: fetch only public sources and leave the executables in $PREFIX/bin. To change an agent without a gap, use upsert rather than remove and add.

​
The run contract

Your run_command runs with sh -c at the task’s working directory, and can rely on exactly this:
  • The instruction arrives twice: on stdin, and at the path in $EVOLVE_INSTRUCTION_FILE.
  • $EVOLVE_GATEWAY_BASE_URL is an OpenAI-compatible base URL that already ends in /v1, and $EVOLVE_GATEWAY_API_KEY is its credential. The same two values are also $OPENAI_BASE_URL and $OPENAI_API_KEY, so a CLI that reads its endpoint from the environment works unchanged.
  • $EVOLVE_MODEL is the model_name of the arm.
  • Your declared env may not override those six keys, and may not look like a credential; both are refused at registration with agent_invalid_env.
A CLI that routes through a config file must write that file inside run_command, from the contract values. codex is the worked example:
A CLI that ignores OPENAI_BASE_URL without this reaches for its vendor’s endpoint, finds the box sealed, and spends the agent budget failing to connect. The spend cap is airtight only under no-network; see models. Against a built-in, a registered agent has no live trace (there is no parser for an unknown CLI) and no reasoning_effort (put the flag in run_command); everything else is recorded the same way.

agent reference

Every flag of evolve agent.