Skip to content

docs: document harness-specific model IDs for oz agent run-cloud #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

Open
hongyi-chen wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: document harness-specific model IDs for oz agent run-cloud #440

Changes from all commits
Commits
Show all changes
3 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
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: 26 additions & 5 deletions src/content/docs/reference/cli/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,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](/reference/cli/#collaboration)).
* `--profile <ID>` — use a specific agent profile (see [Using Agent Profiles](/reference/cli/#using-agent-profiles)).
* `--model <MODEL_ID>` — override the default model (see [Model Choice](/agent-platform/inference/model-choice/)).
* `--model <MODEL_ID>` — override the default model. Run `oz model list` to see the available IDs, or see [Model Choice](/agent-platform/inference/model-choice/).
* `--skill <SPEC>` — use a skill as the base prompt (see [Using Skills](/reference/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 @@ -265,7 +265,7 @@ oz agent run-cloud \
* `--name <NAME>` (`-n`) — label the run for grouping and traceability (see [Naming runs](/reference/cli/#naming-runs) 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](/reference/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>` — override the default model. With the default `oz` harness, use an ID from `oz model list`. With `--harness claude` or `--harness codex`, pass a harness-specific model ID instead (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](/reference/cli/#using-skills)).
* `--host <WORKER_ID>` — run on a specific self-hosted worker instead of Warp-hosted infrastructure.
* `--attach <PATH>` — attach an image file to the agent query. Can be repeated (maximum 5).
Expand All @@ -274,9 +274,6 @@ oz agent run-cloud \
* `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Only valid with `--harness claude`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).
* `--codex-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Codex harness. Only valid with `--harness codex`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).
* `--file <PATH>` (`-f`) — load run configuration from a YAML or JSON file.
* `--harness <HARNESS>` — choose the [execution harness](/platform/harnesses/) for the run: `oz` (default, Warp's built-in agent infrastructure), `claude` (Claude Code), or `codex`.
* `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Claude Code harness. Only valid with `--harness claude`.
* `--codex-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Codex harness. Only valid with `--harness codex`.

To run a third-party harness, first store the provider credential as a Warp-managed secret, then pass it with the matching flag:

Expand Down Expand Up @@ -348,6 +345,30 @@ oz agent run-cloud \

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.

##### Selecting a model for a third-party harness

`--model` accepts harness-specific model IDs. Warp passes the value straight through to the harness instead of resolving it against Warp's own model list, so use the identifier the harness expects:

```sh

@oz-for-oss oz-for-oss Bot Jul 31, 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.

💡 [SUGGESTION] Use bash for terminal command fences so syntax highlighting matches the docs style guide.

Suggested change
```sh
```bash

# Claude Code model ID
oz agent run-cloud \
--environment <ENVIRONMENT_ID> \
--harness claude \
--claude-auth-secret <SECRET_NAME> \
--model opus \
--prompt "review the latest PR"

# Codex model ID
oz agent run-cloud \
--environment <ENVIRONMENT_ID> \
--harness codex \
--codex-auth-secret <SECRET_NAME> \
--model gpt-5.5 \
--prompt "review the latest PR"
```

`oz model list` only reports models for the built-in `oz` harness. For the accepted values with `--harness claude` or `--harness codex`, consult that harness's own documentation. An unrecognized ID is rejected by the harness, not by Warp.

## Using agent profiles

Agent profiles control what the agent can do, how it behaves, and where it can act. Use the `--profile` flag with `oz agent run` to apply a specific profile.
Expand Down
Loading