> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Harness

> Choose the runtime that drives your agents, pin its exact version, and route model calls to an Anthropic-compatible gateway

A **Harness** is a reusable preset for *what drives an agent*: the agent
runtime and its exact version, an optional Anthropic-compatible LLM provider,
and advanced runtime settings. Configure it once, then pick it on any agent,
context builder, app builder, or the data builder.

Without a harness, everything runs on the built-in **Claude Agent SDK** against
stock Anthropic. Create a harness when you need to:

* **Pin the runtime version** so an image update never changes agent behavior.
* **Route model calls to your own gateway** -- an LLM proxy, a self-hosted model
  server, or another provider's Anthropic-compatible endpoint.
* **Tune the runtime** -- compaction, thinking budget, timeouts.

## Open Harnesses

Open the **More** menu on the left rail and choose **Harnesses**. Each card
summarizes the preset, for example
`sdk@0.3.204 · gateway.example.com · my-model · 2 advanced settings`, or
`built-in SDK · stock Anthropic`.

Admins and Builders can create, edit, and delete harnesses. Every member can
view them.

***

## Runtime: Claude Agent SDK vs Codex

| Runtime | Status |
| - | - |
| **Claude Agent SDK** | Available, and the default. Agents run on Anthropic's Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) inside the sandbox. |
| **Codex** | Listed in the **Runtime** picker as **coming soon**. It cannot be selected or pinned yet. |

The runtime is fixed once the harness is created; to switch runtimes, create a
new harness.

***

## Create a harness

<Steps>
  <Step title="Start the dialog">
    Click **New harness**.
  </Step>

  <Step title="Name and runtime">
    Enter a **Name** (unique in the workspace, e.g. `gateway-prod`) and an
    optional **Description**. Leave **Runtime** on **Claude Agent SDK**.
  </Step>

  <Step title="Pin a version (optional)">
    Enter an exact **Version**, or leave it blank for the built-in default.
  </Step>

  <Step title="Point at a gateway (optional)">
    Fill in the **LLM provider** fields to route model calls to an
    Anthropic-compatible endpoint.
  </Step>

  <Step title="Add advanced settings (optional)">
    Use **+ Add setting…** to tune the runtime.
  </Step>

  <Step title="Create">
    Click **Create**, then select the harness on your agents.
  </Step>
</Steps>

### Version pinning

| Field | What it does |
| - | - |
| **Version** | The exact Claude Agent SDK version, e.g. `0.3.204`. Blank uses the SDK built into the sandbox image (fastest). |

* Only exact versions are accepted -- no tags such as `latest` and no ranges such
  as `^0.3`. A floating tag would defeat the pin.
* A pinned version that differs from the built-in one is installed inside the
  sandbox when the run starts, which adds start-up time.
* Pin a version when you validated your agents against it, or when your gateway
  requires specific wire behavior.

***

## LLM provider (Anthropic-compatible gateway)

Leave **Claude base URL** blank to use stock Anthropic; the other provider fields
stay disabled. Fill it in to send every model call to your own endpoint.

| Field | Env var set in the sandbox | What it does |
| - | - | - |
| **Claude base URL** | `ANTHROPIC_BASE_URL` | An Anthropic-compatible endpoint (`http://` or `https://`), e.g. `https://gateway.example.com/anthropic`. |
| **Auth token secret** | `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` | The **name** of a workspace secret that holds the provider's key. Its value is sent to the gateway in place of your Anthropic key. **No secret (use default auth)** reuses the existing `ANTHROPIC_API_KEY`. |
| **Provider model** | `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` | The model id the provider serves, e.g. `my-model`. |
| **Provider small model** | `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_SMALL_FAST_MODEL`, `CLAUDE_CODE_SUBAGENT_MODEL` | The model for fast, background, and subagent calls. Blank uses **Provider model**. |

### How the auth token secret works

The **Auth token secret** stores only a *name*, never the key itself:

<Steps>
  <Step title="Store the provider key as a workspace secret">
    Add the gateway's key under Workspace settings -> **Secrets**, for example
    with the name `gateway_api_key`. The picker lists the workspace's secrets.
  </Step>

  <Step title="Select it on the harness">
    Choose it under **Auth token secret**. Saving checks that the name exists as
    a workspace secret or as a Secret slot in the workspace's Default
    [vault](/foundation/vault); an unknown name is rejected.
  </Step>

  <Step title="At run time">
    DataGen looks the name up first among the Secrets the run's vault provides
    (matched case-insensitively, hyphens as underscores), then among workspace
    secrets. The value is exported as both `ANTHROPIC_AUTH_TOKEN` (sent as a
    Bearer token) and `ANTHROPIC_API_KEY` (sent as `x-api-key`), so gateways
    that accept either header work, and your real Anthropic key never reaches
    the custom URL.
  </Step>
</Steps>

<Warning>
  With **No secret (use default auth)**, the existing `ANTHROPIC_API_KEY` from
  the vault or workspace secrets is sent to the custom base URL. Select an
  auth token secret whenever the gateway is not operated by you or does not
  expect your Anthropic key. A Claude subscription OAuth token is always
  removed when a custom base URL is set.
</Warning>

### Model precedence

When **Provider model** is set, every agent bound to the harness runs on it. The
agent's **Default model** and any automation's model are ignored, and the agent
settings show a note saying which model the agent always runs on. Leave
**Provider model** blank to let each agent's default model apply.

***

## Advanced settings

**+ Add setting…** offers an allowlist of runtime settings. Each one is injected
into the sandbox as the env var of the same name; only these keys are accepted.

| Setting | Type | Default |
| - | - | - |
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` -- context window used to trigger auto-compaction | tokens, 10,000 - 2,000,000 | model's full window |
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` -- % of the window at which auto-compaction fires | 1 - 100 | \~70 |
| `MAX_THINKING_TOKENS` -- extended-thinking budget | tokens, 0 - 200,000 | model default |
| `CLAUDE_CODE_EFFORT_LEVEL` -- reasoning effort | `low`, `medium`, `high`, `xhigh` | model default |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` -- max output tokens per response | tokens, 1,000 - 128,000 | model default |
| `API_TIMEOUT_MS` -- HTTP timeout for API requests | ms, 1,000 - 3,600,000 | 600000 |
| `BASH_DEFAULT_TIMEOUT_MS` -- default Bash command timeout | ms, 1,000 - 3,600,000 | 120000 |
| `BASH_MAX_TIMEOUT_MS` -- hard ceiling on Bash timeouts | ms, 1,000 - 3,600,000 | 600000 |
| `MCP_TIMEOUT` -- MCP server startup timeout | ms, 1,000 - 600,000 | 30000 |
| `MCP_TOOL_TIMEOUT` -- single MCP tool call timeout | ms, 1,000 - 3,600,000 | 30000 - 60000 |
| `BASH_MAX_OUTPUT_LENGTH` -- Bash output length before truncation | chars, 1,000 - 10,000,000 | \~100000 |
| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` -- strip Anthropic/cloud credentials from subprocesses | on / off | off |
| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` -- disable automatic memory | on / off | off |
| `CLAUDE_CODE_DISABLE_ATTACHMENTS` -- disable attachment processing | on / off | off |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` -- disable telemetry and update checks | on / off | off |

<Tip>
  Gateways that translate to OpenAI-style backends (for example vLLM) may reject
  the effort value `high`. Set `CLAUDE_CODE_EFFORT_LEVEL` to `medium` for them.
</Tip>

***

## Where a harness is selected

| Where | Setting | When left on the default |
| - | - | - |
| **Agent** | **Harness & model** card -> **Harness**, then **Save** | **Default (built-in SDK, stock Anthropic)** |
| **Context builder** | Context settings -> **Harness** | **Default (built-in SDK, stock Anthropic)** |
| **App builder** | App Builder -> **Harness** (the runtime and model the builder's chat runs on) | **Workspace default** |
| **Data builder** | Data -> **Builder configuration** -> **Harnesses** | Built-in SDK, stock Anthropic |

***

## Gotchas

<AccordionGroup>
  <Accordion title="Agents ignore their default model">
    The harness pins a **Provider model**. Clear it on the harness, or bind those
    agents to a different harness.
  </Accordion>

  <Accordion title="Gateway returns 404 for a model">
    Some providers cannot map Claude model names. Set both **Provider model**
    and **Provider small model** so every model slot -- including subagents and
    fast background calls -- uses a model the provider serves.
  </Accordion>

  <Accordion title="Saving fails with an unknown secret name">
    The **Auth token secret** must exist as a workspace secret or as a Secret in
    the Default vault before you save. Create it first, then select it.
  </Accordion>

  <Accordion title="Clearing the base URL">
    Clearing **Claude base URL** also clears the auth token secret and both
    model fields, so the harness returns to stock Anthropic cleanly.
  </Accordion>

  <Accordion title="Deleting a harness">
    Agents pinned to it fall back to the built-in default (built-in SDK, stock
    Anthropic).
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Data overview" icon="database" href="/data/overview">
    Connect a database and publish data models your agents can query.
  </Card>

  <Card title="Build an agent" icon="robot" href="/agents/build">
    Put the vault, sandbox environment and harness together on an agent.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.