> ## Documentation Index > Fetch the complete documentation index at: https://docs.aui.io/llms.txt > Use this file to discover all available pages before exploring further. # Beta runtime > Build new agents and try existing ones on Beta, the newest runtime, from the Apollo CLI and its TUI. 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. | You want to… | CLI | TUI | | - | - | - | | Start a new agent on Beta | `apollo agent create "" --beta` | `Ctrl+K` → `agent-create` → `+` → **Build on Beta (the newest runtime)** | | Try your current version on Beta | `apollo version try-beta` | `Ctrl+K` → `try-beta` | | See where your version stands | `apollo version try-beta --dry-run` | The header badge and the Versions view | | See which versions run on Beta | `apollo version list` | **BETA** in the header and in Versions | | Go back to your own version | `apollo version use `, then `apollo pull` | `Ctrl+K` → `branch-use` | > [!NOTE] > > 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: ```bash theme={"dark"} apollo version try-beta --dry-run ``` ```text wrap theme={"dark"} Beta runtime: Branch: v2 "Returns flow" (v2.4) — runs on the default deployment Try Beta: `apollo branch try-beta` cuts a Beta branch from it and rebuilds it there ``` 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`: ```bash theme={"dark"} apollo agent create "Returns Assistant" --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`. ```text wrap theme={"dark"} Created agent Returns Assistant in ~/apollo/…/returns-assistant-… (bound v0.1) on runtime . On Beta: it and every branch made from it run on the Beta runtime . Checked out v0.1: 1 program file(s) — `apollo diff` starts clean. ``` > [!TIP] > > 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: ```bash theme={"dark"} apollo version try-beta ``` **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](https://docs.aui.io/cli/commands.md#apollo-build) 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. ```text wrap theme={"dark"} Creating the Beta branch "Beta" from v2.4... Checking out v3.1 from Beta... Rebuilding and evaluating it on Beta (this can take a few minutes)... Beta branch ready: "Beta" (v3.1), cut from v2.4 — it runs on the Beta runtime (engine ). v2 "Returns flow" (v2.4) is unchanged; `apollo branch use v2.4` goes back to it. This checkout is on v3.1 now, and every command here goes to Beta. Build completed — pushed v3.2 (…). pulled: the checkout now matches v3.2 ``` Your original version never changes. To go back to it: ```bash theme={"dark"} apollo version use v2.4 # the tag Try Beta named apollo pull # bring its files back into the checkout ``` ### Options | Option | Description | | - | - | | `--dry-run` | Say whether the version runs on Beta and whether Try Beta would run here. Writes nothing | | `--no-build` | Move onto the new Beta version without the rebuild. Run `apollo build "Rebuild the program and evaluate it"` there yourself | | `--model ` | Build model for the rebuild | | `--max-usd ` | Spend cap for the rebuild turn | ### When Try Beta asks for something first | Situation | What to do | | - | - | | Your version is on an older runtime, so **Upgrade to latest** comes first | Run the upgrade steps that Try Beta lists (below), then try again | | Your checkout has changes the server doesn't have | Push them with `apollo push`, or discard them with `apollo pull --force` | | Your version already runs on Beta | Nothing to do: it's already on Beta | | No Beta runtime is offered right now | Try again when one is: `apollo version try-beta --dry-run` tells you | Try Beta prints the upgrade steps (`UPGRADE_FIRST`) with the newest runtime in place of ``: ```bash theme={"dark"} # Re-pin and refresh the checkout apollo runtime use # Keep a copy of the current state apollo push -m "Before upgrading to " # Upgrade the program under it apollo build "Upgrade this agent runtime version" # Then try it on Beta apollo version try-beta ``` *** ## See what runs on Beta ```bash theme={"dark"} apollo version list # BETA marks every version on Beta apollo status --check # Version: v3.2 BETA apollo runtime show # where the checkout's version runs apollo runtime list # marks the Beta runtime ``` ```text theme={"dark"} v3 draft BETA Beta newest v3.2 from v2.4 v2 draft Returns flow newest v2.4 from v1.3 v1 draft Initial Version newest v1.3 live v1.3 ``` `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. > [!WARNING] > > Beta is for building and trying agents. Conversations through the [Messaging API](https://docs.aui.io/api/messaging/send-messages.md) 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](#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](https://docs.aui.io/cli/commands.md): `{"success": true, "data": …}` or `{"success": false, "error": {"code", "message", "suggestion"}}`. ```bash theme={"dark"} apollo --json --no-input version try-beta --dry-run apollo --json --no-input version try-beta [--no-build] apollo --json --no-input agent create "Returns Assistant" --beta apollo --json --no-input version list apollo --json --no-input status --check ``` | Command | What `data` carries | | - | - | | `version try-beta --dry-run` | `beta` (the Beta runtime, or `null` when none is offered) and, inside a checkout, `checkout` with `on_beta`, `upgrade` (`{from, to, to_label}` when **Upgrade to latest** comes first) and `try_blocked` (why Try Beta wouldn't run on this version; absent when it would) | | `version try-beta` | `agent_id`, `from`, `branch` (the new Beta version), `beta`, `runtime_version`, `binding`, `pull`, and `rebuild` (`null` with `--no-build`) | | `agent create --beta` | The usual create result, plus `beta: {name, display_name}` | | `version list` | `beta: true` on every version line that runs on Beta | | `status --check` | `onBeta: true` when the checkout's version runs on Beta | 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 > [card] [Command reference](https://docs.aui.io/cli/commands.md) > > Every CLI command, including `agent create --beta` and `version try-beta`. > [card] [Workflows](https://docs.aui.io/cli/workflows.md) > > The edit, validate, test, and push loop you use on Beta too. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.