From 7de40b86725e78d1e9c4e4108d2221dcd9e9340c Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Fri, 4 Sep 2026 23:36:37 +0000 Subject: [PATCH] Clarify harness identifiers and dedupe run-cloud harness flags Document the exact harness identifier strings per surface (API/SDK, CLI, factory definition files), note claude-code is an alias for claude where accepted, and remove the duplicated --harness / --claude-auth-secret / --codex-auth-secret bullets in the run-cloud flag list. Co-Authored-By: Warp --- src/content/docs/factories/factory-as-code.mdx | 2 +- src/content/docs/platform/harnesses/claude-code.mdx | 2 +- src/content/docs/platform/harnesses/index.mdx | 12 +++++++++++- src/content/docs/reference/cli/index.mdx | 5 +---- 4 files changed, 14 insertions(+), 7 deletions(-) diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 391e43f4..ad088d5f 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -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: diff --git a/src/content/docs/platform/harnesses/claude-code.mdx b/src/content/docs/platform/harnesses/claude-code.mdx index adad255b..eb8c70c8 100644 --- a/src/content/docs/platform/harnesses/claude-code.mdx +++ b/src/content/docs/platform/harnesses/claude-code.mdx @@ -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 diff --git a/src/content/docs/platform/harnesses/index.mdx b/src/content/docs/platform/harnesses/index.mdx index ece55969..80b34e26 100644 --- a/src/content/docs/platform/harnesses/index.mdx +++ b/src/content/docs/platform/harnesses/index.mdx @@ -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 diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index 2fa74e60..803c677e 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -273,13 +273,10 @@ oz agent run-cloud \ * `--host ` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--attach ` — 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 ` — 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 ` — 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 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 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 ` (`-f`) — load run configuration from a YAML or JSON file. -* `--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 of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Claude Code harness. Only valid with `--harness claude`. -* `--codex-auth-secret ` — 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: