---
title: "Run a remote agent"
description: "Run a provider-hosted agent loop with tools on your nodes."
canonical_url: "https://docs.oz0.ai/build/apps/remote-agents"
---
# Run a remote agent

> Run a provider-hosted agent loop with tools on your nodes.

For: application developers.

Use a remote agent when the provider should run the model and agent loop while your nodes execute its tool calls. The first supported provider is [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) with a [self-hosted environment](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes).

Anthropic runs the loop; a node executes each session tool call in the job's sandbox.

<table>
<thead>
  <tr>
    <th>
      How an agent runs
    </th>
    
    <th>
      <code>
        runtime:
      </code>
    </th>
    
    <th>
      Where the loop runs
    </th>
    
    <th>
      Where its tools run
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A framework
    </td>
    
    <td>
      <code>
        pydantic-ai
      </code>
    </td>
    
    <td>
      In the job's workflow, one activity per step
    </td>
    
    <td>
      On the job's node
    </td>
  </tr>
  
  <tr>
    <td>
      A harness
    </td>
    
    <td>
      <code>
        harness:&lt;name>
      </code>
    </td>
    
    <td>
      In one session on a node
    </td>
    
    <td>
      In that session
    </td>
  </tr>
  
  <tr>
    <td>
      Remote
    </td>
    
    <td>
      <code>
        remote:&lt;name>
      </code>
    </td>
    
    <td>
      At the provider
    </td>
    
    <td>
      On a node, in the job's sandbox, apart from the keys
    </td>
  </tr>
  
  <tr>
    <td>
      An outside A2A agent
    </td>
    
    <td>
      <code>
        remote:a2a
      </code>
    </td>
    
    <td>
      At the outside agent's host
    </td>
    
    <td>
      At the outside agent's host
    </td>
  </tr>
</tbody>
</table>

An outside agent that speaks the [A2A protocol](https://a2a-protocol.org/latest/specification/), yours or a partner's, an agent on Amazon Bedrock AgentCore Runtime or in Microsoft Foundry, can be an agent of your catalog too: see [Outside A2A agents](https://docs.oz0.ai/build/apps/remote-agents/a2a#outside-a2a-agents).

## When to use it

- You want Anthropic's agent harness, context management and models, but your files, commands and network stay on your machines.
- The agent needs the node's tools: your MCP plugins, internal services, the repository on the node.
- You accept that the conversation, including every tool's input and output, is processed by Anthropic (see below).

Not for air-gapped sites: a node must reach `api.anthropic.com`.

## Set it up

1. In the [Claude Console](https://platform.claude.com/), create a self-hosted environment (Workspace > Environments > New > Self-hosted) and click Generate environment key. A workspace of its own for Orchestrator Zero keeps its sessions and keys apart.
2. Store the API key, the environment key and the environment's ID as the tenant's secrets:```bash
printf %s "$KEY" | oz0 secret set ANTHROPIC_MANAGED_AGENTS_KEY
printf %s "$ENVIRONMENT_KEY" | oz0 secret set ANTHROPIC_ENVIRONMENT_KEY
printf %s env_... | oz0 secret set ANTHROPIC_ENVIRONMENT_ID
```
3. Install the provider's plugin on the nodes that should run the tools:```bash
oz0 plugin install <git url of the repository> --path plugins/remote-claude-managed
```

## The agent definition

```yaml [agents/acme-managed-coder.yaml]
name: acme-managed-coder
description: Makes small changes to code with Claude Managed Agents.
runtime: remote:claude-managed
model:
  primary: anthropic/claude-sonnet-5-5
instructions: prompts/acme-managed-coder.md
input: text
output: text
tools: [jev.check, oz.ask_user]   # the node's tools it may call, and asking people
limits:
  timeout: 30m
harness:
  tools: [bash, read, write, edit, glob, grep]   # the built-ins it gets (these are the default)
  requires_approval: [bash]       # a person approves each command
  max_budget_usd: 5               # the session's own hard cap at Anthropic
```

<table>
<thead>
  <tr>
    <th>
      Harness option
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        tools
      </code>
    </td>
    
    <td>
      The built-in tools the session gets: <code>
        bash
      </code>
      
      , <code>
        read
      </code>
      
      , <code>
        write
      </code>
      
      , <code>
        edit
      </code>
      
      , <code>
        glob
      </code>
      
      , <code>
        grep
      </code>
      
      , which run on the node, and <code>
        web_search
      </code>
      
      , <code>
        web_fetch
      </code>
      
      , which run at Anthropic. Every other built-in is off.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        requires_approval
      </code>
    </td>
    
    <td>
      Built-ins whose every call waits for a person, as <code>
        claude-managed.&lt;tool>
      </code>
      
       in the approvals inbox.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        max_budget_usd
      </code>
    </td>
    
    <td>
      Becomes the provider session's budget (<code>
        max_list_cost
      </code>
      
      ): Anthropic stops the session there, whatever happens on the node.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        session_hour_usd
      </code>
    </td>
    
    <td>
      What an hour of a session's running time costs, for the cost split below; $0.08 by default.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        workspace
      </code>
    </td>
    
    <td>
      The Console workspace's ID, to link each session's trace view in the live stream.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        keep_session
      </code>
    </td>
    
    <td>
      Leave sessions open at Anthropic when they end, instead of archiving them (they are marked <code>
        oz0_ended
      </code>
      
       in their metadata).
    </td>
  </tr>
</tbody>
</table>

There is no option for the API's address: any plugin may define an agent on `claude-managed`, and an agent definition must not choose where the tenant's keys go, so `harness: api_url` fails `plugin lint` and the job. Sessions go to `https://api.anthropic.com`. A node's operator can point a remote harness elsewhere, such as at a gateway in front of the API or a test's fake, with an environment variable of the node:

```bash
OZ0_REMOTE_API_URLS="claude-managed=https://anthropic-gateway.internal" oz0-node run
```

The address must be https, or http to the node itself.

`limits.max_steps` counts the session's model requests at Anthropic, over all its segments: the request after the last one allowed ends the session and fails the job. Without it, Anthropic's own limits and `max_budget_usd` apply.

Tools, hooks and approvals name the built-ins `claude-managed.bash`, `claude-managed.write` and so on, as for any [harness](https://docs.oz0.ai/build/parts/harnesses). The node's tools keep their own names (`jev.check`).

## Related tasks

- [Remote sessions and limits](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits): Understand execution, cost and data leaving the network.
- [Connect an outside A2A agent](https://docs.oz0.ai/build/apps/remote-agents/a2a): Add a remote A2A service to your tenant catalog.

<legacy-sections>

- <span id="amazon-bedrock-agentcore-and-microsoft-foundry">

Section

</span>

: [amazon bedrock agentcore and microsoft foundry](https://docs.oz0.ai/build/apps/remote-agents/a2a#amazon-bedrock-agentcore-and-microsoft-foundry)
- <span id="an-outside-agent-is-its-cards-origin">

Section

</span>

: [an outside agent is its cards origin](https://docs.oz0.ai/build/apps/remote-agents/a2a#an-outside-agent-is-its-cards-origin)
- <span id="budgets-what-they-bound-and-what-they-cannot">

Section

</span>

: [budgets what they bound and what they cannot](https://docs.oz0.ai/build/apps/remote-agents/a2a#budgets-what-they-bound-and-what-they-cannot)
- <span id="calls-back-into-this-cluster">

Section

</span>

: [calls back into this cluster](https://docs.oz0.ai/build/apps/remote-agents/a2a#calls-back-into-this-cluster)
- <span id="cost">

Section

</span>

: [cost](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits#cost)
- <span id="input-from-outside">

Section

</span>

: [input from outside](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits#input-from-outside)
- <span id="limits-today">

Section

</span>

: [limits today](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits#limits-today)
- <span id="outside-a2a-agents">

Section

</span>

: [outside a2a agents](https://docs.oz0.ai/build/apps/remote-agents/a2a#outside-a2a-agents)
- <span id="stopping">

Section

</span>

: [stopping](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits#stopping)
- <span id="the-audit-log">

Section

</span>

: [the audit log](https://docs.oz0.ai/build/apps/remote-agents/a2a#the-audit-log)
- <span id="what-happens-in-a-job">

Section

</span>

: [what happens in a job](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits#what-happens-in-a-job)
- <span id="what-happens-in-a-job-1">

Section

</span>

: [what happens in a job 1](https://docs.oz0.ai/build/apps/remote-agents/a2a#what-happens-in-a-job-1)
- <span id="what-leaves-your-network">

Section

</span>

: [what leaves your network](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits#what-leaves-your-network)
- <span id="what-leaves-your-network-1">

Section

</span>

: [what leaves your network 1](https://docs.oz0.ai/build/apps/remote-agents/a2a#what-leaves-your-network-1)
- <span id="when-a-node-is-lost">

Section

</span>

: [when a node is lost](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits#when-a-node-is-lost)
- <span id="where-the-keys-are">

Section

</span>

: [where the keys are](https://docs.oz0.ai/build/apps/remote-agents/sessions-and-limits#where-the-keys-are)

</legacy-sections>


## Sitemap

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