Skip to main content
The Beta runtime is the newest version of the runtime, offered so you can build and try agents on it before it’s released. The Apollo CLI gives you two ways to use it:
  • Build on Beta: create a new agent that runs on Beta, together with every version you make from it.
  • Try Beta: try an existing agent on Beta in a new version, without touching the version you’re on.
Both work from the command line and from the TUI.
Beta needs Apollo CLI 0.1.107 or later. Run apollo upgrade to update. apollo version is the same command as apollo branch, which is the name the CLI’s help and the TUI use.

​
Before you start

Beta is available when AUI offers a Beta runtime, one at a time. To check, run this inside an agent’s checkout:
The dry run writes nothing. The first line names the Beta runtime, or says that none is offered right now. apollo runtime list also marks the Beta runtime.

​
Build on Beta

Create the agent with --beta:
1

The agent is created on the Beta runtime

Like every apollo agent create, this doesn’t start a build. You get an empty draft, ready to edit.
2

It stays on Beta

The agent, and every version you make from it later, runs on Beta.
3

Your checkout follows

The new checkout talks to Beta for every command you run in it: validate, push, pull, build, and chat.
Only --beta creates an agent on Beta. Without it, a new agent starts on the newest published runtime, even when you run apollo agent create inside a Beta agent’s checkout. --beta chooses the runtime itself, so don’t combine it with --runtime-version.

​
Try Beta

Run Try Beta inside the agent’s checkout, on the version you want to try:
1

A new version labelled Beta

Try Beta copies the version your checkout is on into a new draft version labelled Beta. If that label is taken, it uses Beta 2, Beta 3, and so on.
2

That version runs on Beta

Only the new version is set to run on the Beta runtime. Your other versions don’t change.
3

Your checkout moves onto it

The checkout switches to the new version and pulls it from Beta: the program files, and the schemas, skills, and AGENTS.md that the Beta runtime serves.
4

The builder rebuilds and evaluates it on Beta

A build turn rebuilds the program on Beta and evaluates it. When the build passes, it pushes the result as the next version on the Beta line. This takes a few minutes.
Your original version never changes. To go back to it:

​
Options

​
When Try Beta asks for something first

Try Beta prints the upgrade steps (UPGRADE_FIRST) with the newest runtime in place of <newest>:

​
See what runs on Beta

apollo push and apollo pull also say when they ran on Beta.

​
Work on a version on Beta

A version on Beta works like any other: edit it, then use apollo validate, apollo push, apollo pull, apollo build, and apollo chat as usual. In that checkout, they all run against the Beta runtime.
  • Upgrade to latest never applies to a version on Beta.
  • To talk to the agent on Beta, use apollo chat in its checkout, or Talk in the TUI.
Beta is for building and trying agents. Conversations through the Messaging API don’t run on Beta yet.

​
In the TUI

Open the TUI with apollo (no arguments) inside the agent’s checkout.

​
Run Try Beta

Press Ctrl+K, type try-beta (or beta), and press Enter. This runs the whole flow from Try Beta: the new Beta version, the checkout move, and the rebuild and evaluation on Beta. While it works, the apollo label and the input border turn amber. When it finishes:
  • the toast says On Beta: Beta rebuilt as v3.2;
  • the result pane shows the new version, the one it came from, and how to go back;
  • the header reads Returns Assistant @ v3.2 BETA.

​
Create an agent on Beta

  1. Press Ctrl+K, type agent-create, and press Enter.
  2. Fill in Name and Directory.
  3. Press + to show the advanced options, set Build on Beta (the newest runtime) to y, and press Enter.
The TUI creates the agent on Beta and opens its checkout. The header shows Returns Assistant @ v0.1 BETA.

​
BETA badges

The header shows BETA next to the version whenever the checkout’s version runs on Beta. The Versions view (r, or Ctrl+K → versions) marks every version line on Beta.

​
For coding agents and scripts

Every Beta command is non-interactive and takes the global --json flag. Each run writes one JSON envelope: {"success": true, "data": …} or {"success": false, "error": {"code", "message", "suggestion"}}.
Error codes to handle: UPGRADE_FIRST (exit 3, with the upgrade steps in suggestion) and CONFIG_ERROR (exit 3, for example when no Beta runtime is offered or the checkout has unpushed changes). try_blocked covers the checks on the version itself, and local changes are checked when Try Beta runs.

​
Next steps

Command reference

Every CLI command, including agent create --beta and version try-beta.

Workflows

The edit, validate, test, and push loop you use on Beta too.