Skip to content

docs: Clarify harness identifiers (claude vs claude-code) and dedupe run-cloud flags #689

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

Draft
hongyi-chen wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Clarify harness identifiers (claude vs claude-code) and dedupe run-cloud flags #689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion src/content/docs/factories/factory-as-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ harness:

### `agentDefaults.harness`

The harness and model that runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude` (alias `claude-code`), `codex`, or `gemini` — the values the definition schema validates. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/).
The harness and model that runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude`, `codex`, or `gemini` — the values the definition schema validates. `claude-code` is also accepted as an alias for `claude`; prefer `claude`, the canonical [harness identifier](/platform/harnesses/#harness-identifiers) that the CLI and the Agent API use for the same harness. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/).

```yaml
harness:
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/platform/harnesses/claude-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/au

* **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Claude Code**.
* **{VARS.WEB_APP}** - On the new run or new schedule pane, choose **Claude Code** in the **Harness** field. A **Claude Code auth secret** field appears below it; pick one of your stored Anthropic secrets.
* **API and SDK** - Set the agent config `harness` to `claude` and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/).
* **API and SDK** - Set the agent config `harness` to `claude` — the [harness identifier](/platform/harnesses/#harness-identifiers) is `claude`, not `claude-code` — and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/).

## Related pages

Expand Down
12 changes: 11 additions & 1 deletion src/content/docs/platform/harnesses/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,17 @@ On the new run or new schedule pane, choose the harness in the **Harness** field

### API and SDK

Set the `harness` field on the agent config. See the [API reference](/reference/api-and-sdk/) for the exact field names.
Set the `harness` field on the agent config to one of the [harness identifiers](#harness-identifiers) below. See the [API reference](/reference/api-and-sdk/) for the exact field names.

## Harness identifiers

Surfaces that take the harness as a string all use the same identifiers: `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex. Write `claude` for Claude Code — not `claude-code`:

* **API and SDK** — the agent config's `harness.type` accepts `oz`, `claude`, or `codex`.
* **CLI** — `oz agent run-cloud --harness` accepts the same identifiers, plus `claude-code` as an alias for `claude`.
* **Factory definition files** — [`harness.type`](/factories/factory-as-code/#agentdefaultsharness) accepts the same identifiers, plus the `claude-code` alias.

Where the alias is accepted, it selects the same Claude Code harness as `claude`. Everywhere else — including the API — only the canonical identifiers are valid, so prefer them in anything you script, sync, or store.

## Related pages

Expand Down
5 changes: 1 addition & 4 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 @@ -273,13 +273,10 @@ oz agent run-cloud \
* `--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).
* `--computer-use` / `--no-computer-use` — enable or disable [Computer Use](/agents/capabilities/computer-use/) for this run.
* `--harness <HARNESS>` — choose the execution harness for the run. Defaults to `oz` (Warp Agent). Set `claude` or `codex` to run [Claude Code or Codex as a cloud agent](/platform/harnesses/).
* `--harness <HARNESS>` — choose the [execution harness](/platform/harnesses/) for the run: `oz` (default, the Warp Agent), `claude` (Claude Code), or `codex` (Codex). `claude-code` is accepted as an alias for `claude`. See [harness identifiers](/platform/harnesses/#harness-identifiers).
* `--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
Loading