---
title: "Choose a harness"
description: "Choose an existing runtime and understand what a harness session receives."
canonical_url: "https://docs.oz0.ai/build/parts/harnesses"
---
# Choose a harness

> Choose an existing runtime and understand what a harness session receives.

For: plugin authors.

Use a harness plugin to run an existing agent runtime as one process per job on a node. Each job becomes one session of that harness.

For example, the Claude Agent SDK supplies file reading and editing, search, command execution, skills and subagents. A harness adapter makes those capabilities available within Orchestrator Zero's job controls.

## Use the Claude Agent SDK

The official harness plugin is `harness-claude`. Install it on the nodes that should run harness agents, and set the tenant's Anthropic key once:

```bash [Terminal]
oz0 plugin install <git url of the harness-claude plugin>
printf %s "$ANTHROPIC_API_KEY" | oz0 secret set ANTHROPIC_API_KEY
```

Then give an agent, in any plugin, `runtime: harness:claude-agent-sdk`:

```yaml [agents/acme-coder.yaml]
name: acme-coder
description: Makes small changes to code and runs the tests.
runtime: harness:claude-agent-sdk
model:
  use: smart                          # a tenant alias; any provider record that takes Anthropic's Messages API
instructions: prompts/acme-coder.md   # added to the SDK's own system prompt
limits:
  max_steps: 30                       # turns
  timeout: 30m
harness:                              # options for the harness, passed on as they are
  tools: [Read, Write, Edit, Glob, Grep, Bash]   # the default; anything else is refused
  permission_mode: acceptEdits        # default, acceptEdits, plan or bypassPermissions
  system_prompt: append               # or replace, to use only the instructions
  max_budget_usd: 2.0                 # the SDK stops the session at this cost
```

Run it like any agent: `oz0 run acme-coder "Fix the failing test in tests/test_dates.py"`. Its text and tool calls appear in the live stream, and its model calls are metered under the job.

## What a session gets

### An empty working directory

The session gets its own working directory, removed when it ends, and a private state directory for the harness's configuration. A session without a sandbox (tier 0) also gets a temporary folder of its own (`TMPDIR`), removed with them, so what its programs leave there does not stay on the node. It is a short folder in the node's temporary folder, not under the session's, so that a Unix socket a program binds there stays within the limit on a socket's path. A node killed in the middle of a session leaves these folders behind ([temporary session files](https://docs.oz0.ai/reference/files#temporary-session-files)).

- No user, project or local settings, no memory between sessions, no telemetry and no auto-update.
- The node's LLM proxy as its API, so the tenant's key stays in the edge, with the job and agent on every call so the gateway meters the session.
- A minimal environment: never the Temporal proxy's token or a provider key.
- Its agent's [skills](https://docs.oz0.ai/build/parts/skills), as a read-only folder beside its own folders, outside the working directory: the Claude Agent SDK loads it as a plugin of that session only, with the `Skill` tool (allowed for an agent with skills, and decided by the job like any call); an ACP harness's tool reads it where the harness's `acp.skills` says. A harness of your own gets the folder's path as `skills_dir` and the names as `skills` in its session request.

## Related tasks

- [Harness tool controls](https://docs.oz0.ai/build/parts/harnesses/tool-controls): Apply hooks, policy and approval to a harness session.
- [Recover a harness session](https://docs.oz0.ai/build/parts/harnesses/recovery): Understand node loss and restart-safe sessions.
- [Write a harness](https://docs.oz0.ai/build/parts/harnesses/custom-harnesses): Wrap a framework or implement the harness protocol.
- [Use an ACP agent](https://docs.oz0.ai/build/parts/harnesses/acp): Configure ACP harnesses and enforce their session controls.

<legacy-sections>

- <span id="add-an-acp-agent">

Section

</span>

: [add an acp agent](https://docs.oz0.ai/build/parts/harnesses/acp#add-an-acp-agent)
- <span id="agents-that-speak-acp">

Section

</span>

: [agents that speak acp](https://docs.oz0.ai/build/parts/harnesses/acp#agents-that-speak-acp)
- <span id="frameworks-as-harnesses">

Section

</span>

: [frameworks as harnesses](https://docs.oz0.ai/build/parts/harnesses/custom-harnesses#frameworks-as-harnesses)
- <span id="hooks-and-approvals-for-the-sessions-tools">

Section

</span>

: [hooks and approvals for the sessions tools](https://docs.oz0.ai/build/parts/harnesses/tool-controls#hooks-and-approvals-for-the-sessions-tools)
- <span id="restart-safety">

Section

</span>

: [restart safety](https://docs.oz0.ai/build/parts/harnesses/recovery#restart-safety)
- <span id="tools-hooks-and-approvals">

Section

</span>

: [tools hooks and approvals](https://docs.oz0.ai/build/parts/harnesses/acp#tools-hooks-and-approvals)
- <span id="use-one">

Section

</span>

: [use one](https://docs.oz0.ai/build/parts/harnesses/acp#use-one)
- <span id="what-a-session-gets-1">

Section

</span>

: [what a session gets 1](https://docs.oz0.ai/build/parts/harnesses/acp#what-a-session-gets-1)
- <span id="when-a-node-is-lost">

Section

</span>

: [when a node is lost](https://docs.oz0.ai/build/parts/harnesses/recovery#when-a-node-is-lost)
- <span id="which-harnesses-ask-before-a-shell-command">

Section

</span>

: [which harnesses ask before a shell command](https://docs.oz0.ai/build/parts/harnesses/tool-controls#which-harnesses-ask-before-a-shell-command)
- <span id="write-a-harness-for-another-tool">

Section

</span>

: [write a harness for another tool](https://docs.oz0.ai/build/parts/harnesses/custom-harnesses#write-a-harness-for-another-tool)

</legacy-sections>


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.