Skip to content

docs: clarify model IDs for cloud agent harnesses #440

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hongyi-chen merged 6 commits into from
Oct 7, 2026
Merged

docs: clarify model IDs for cloud agent harnesses #440

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5091463
docs: document oz agent base prompt flags and harness-specific model IDs
oz-agent Jul 31, 2026
b699893
docs: drop --prompt flag docs already covered by #387
oz-agent Jul 31, 2026
c79a3fb
Merge branch 'main' into docs/cli-agent-prompt-and-harness-models
hongyi-chen Jul 31, 2026
6440dbd
Merge main and refresh harness model docs
warp-agent-staging[bot] Oct 7, 2026
553c443
docs: reduce CLI reference callout density
warp-agent-staging[bot] Oct 7, 2026
451fab3
docs: remove repeated model guidance
warp-agent-staging[bot] Oct 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 14 additions & 17 deletions src/content/docs/agents/cli/oz-cli/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,7 @@ The {VARS.WARP_AGENT_CLI} is automatically distributed with the Warp desktop app
1. Open the [Command Palette](/terminal/command-palette/) (`Cmd+P`)
2. In the search field, find and select the **Install {VARS.WARP_AGENT_CLI} Command** action.

:::note
**Note:** Administrator permissions are required to install the CLI into `/usr/local/bin` .
:::
Administrator permissions are required to install the CLI into `/usr/local/bin`.
</TabItem>
<TabItem label="Windows">
In the Warp installer, select **Add Warp to PATH**. If you are installing for all users, this will put the CLI on the system path. Otherwise, the CLI is only added to the path for your account.
Expand Down Expand Up @@ -83,9 +81,7 @@ Warp provides standalone packages for the CLI on macOS and Linux, without the Wa
* [Apple Silicon, Warp Preview](https://app.warp.dev/download/cli?os=macos\&channel=preview\&package=tar\&arch=aarch64)
* [Intel, Warp Preview](https://app.warp.dev/download/cli?os=macos\&channel=preview\&package=tar\&arch=x86_64)

:::note
**Note:** These builds do not auto-update.
:::
These builds do not auto-update.
</TabItem>
<TabItem label="Linux">
On Linux, we recommend that you install and update the standalone CLI through your distribution's package manager. We support `apt`, `yum`, and `pacman`.
Expand All @@ -102,9 +98,7 @@ Warp provides standalone packages for the CLI on macOS and Linux, without the Wa

```

:::note
**Note:** The package name (`oz-stable`) differs from the CLI command executable (`oz`). After installation, use the CLI via `oz` commands.
:::
The package name (`oz-stable`) differs from the CLI command executable (`oz`). After installation, use the CLI via `oz` commands.

***

Expand Down Expand Up @@ -232,7 +226,7 @@ oz agent run --prompt "set up a new Rust crate named warp-cli"
* `--name <NAME>` (`-n`) — label the run for grouping and traceability.
* `--share` — share the session with teammates (see [Collaboration](/agents/cli/oz-cli/#collaboration)).
* `--profile <ID>` — use a specific agent profile (see [Using Agent Profiles](/agents/cli/oz-cli/#using-agent-profiles)).
* `--model <MODEL_ID>` — override the default model (see [Model Choice](/agents/inference/model-choice/)).
* `--model <MODEL_ID>` — override the default Warp Agent model. Run `oz model list` to see the available IDs, or see [Model choice](/agents/inference/model-choice/).
* `--skill <SPEC>` — use a skill as the base prompt (see [Using Skills](/agents/cli/oz-cli/#using-skills)).
* `--mcp <SPEC>` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated.
* `--environment <ID>` (`-e`) — run in a specific cloud environment.
Expand Down Expand Up @@ -268,7 +262,7 @@ oz agent run-cloud \
* `--parent-run-id <RUN_ID>` — start the run as an orchestration child of an existing run (see [Starting a run as an orchestration child](/agents/cli/oz-cli/#starting-a-run-as-an-orchestration-child) below).
* `--agent <UID>` — run as a saved [named agent](/platform/agents/), applying its configuration (skills, secrets, base model, and default environment) and attributing credit usage to it (see [Managing named agents](/agents/cli/oz-cli/#managing-named-agents) below).
* `--mcp <SPEC>` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated.
* `--model <MODEL_ID>` — override the default model.
* `--model <MODEL_ID>` — choose the model for the selected harness. For the Warp Agent harness, use an ID from `oz model list`. For Claude Code or Codex, see [Choosing an execution harness](#choosing-an-execution-harness).
* `--skill <SPEC>` — use a skill from the environment's repository as the base prompt (see [Using Skills](/agents/cli/oz-cli/#using-skills)).
* `--host <WORKER_ID>` — run on a specific self-hosted worker instead of Warp-hosted infrastructure.
* `--attach <PATH>` — attach a file to the agent query. You can attach up to 25 files, with a maximum size of 10 MB per file. For images in interactive local or cloud conversations, see [Images as Context](/agents/local-agents/agent-context/images-as-context/).
Expand Down Expand Up @@ -363,17 +357,20 @@ You can reuse saved prompts with `--saved-prompt`, and reference notebooks, work

#### Choosing an execution harness

By default, cloud runs use Warp's built-in `oz` harness. To delegate the run to a third-party coding agent, pass `--harness` with `claude` (Claude Code) or `codex`, along with the matching auth secret:
By default, cloud runs use the Warp Agent harness (`oz`). To run Claude Code or Codex, pass `--harness` with the matching auth secret.

```sh
```bash
oz agent run-cloud \
--environment <ENVIRONMENT_ID> \
--environment ENVIRONMENT_ID \
--harness claude \
--claude-auth-secret <SECRET_NAME> \
--claude-auth-secret SECRET_NAME \
--model opus \
--prompt "review the latest PR"
```

Create the auth secret first with `oz secret create claude api-key <SECRET_NAME>` (or `oz secret create codex api-key <SECRET_NAME>` for Codex). See [Third-party cloud agent authentication](/platform/harnesses/authentication/) for the full setup.
Run `oz model list` to list model IDs for the Warp Agent harness. For Claude Code, choose an ID from [available Claude Code models](/platform/harnesses/claude-code/#available-models). For Codex, choose an ID from [available Codex models](/platform/harnesses/codex/#available-models). If the model is not available for the selected harness, the command fails before the run starts.

@warp-agent-staging warp-agent-staging Bot Oct 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The claim is supported by current client and server validation, but the required Agent docs review gate is red because it does not accept the existing pinned source verification. A maintainer needs to decide whether to repair/rerun that gate or add the requested Source files consulted metadata; the sentence should not be weakened solely to satisfy the check.

Responding as Docs Factory (V2): Open session · View in factory


Create the auth secret first with `oz secret create claude api-key SECRET_NAME` (or `oz secret create codex api-key SECRET_NAME` for Codex). See [Third-party cloud agent authentication](/platform/harnesses/authentication/) for the full setup.

## Using agent profiles

Expand Down Expand Up @@ -541,7 +538,7 @@ Repeat `--to` to fan a message out to multiple recipient runs.

### `oz model list`

List all available models:
List available models for the Warp Agent harness:

```sh
oz model list
Expand Down
Loading