Run a remote agent

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 with a self-hosted environment.

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

An outside agent that speaks the A2A protocol, 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.

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, 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:

   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:

   oz0 plugin install <git url of the repository> --path plugins/remote-claude-managed
   

The agent definition

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

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:

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. The node's tools keep their own names (jev.check).

Related tasks

• Remote sessions and limits: Understand execution, cost and data leaving the network.
• Connect an outside A2A agent: Add a remote A2A service to your tenant catalog.