自托管沙箱

在自托管沙箱中运行 Claude Managed Agents 会话,将工具执行、文件和网络出口流量保留在您自己的基础设施中。

“Self-hosted sandboxes”(自托管沙箱)将智能体的工具执行从 Anthropic 托管的云沙箱迁移到您控制的基础设施中,而 Anthropic 继续运行智能体本身。要了解这意味着什么并判断它是否适合您的智能体,请参阅选择智能体环境。

要在您自己的基础设施上运行整个 Managed Agents 服务(而不仅仅是沙箱),请参阅自托管 Claude Managed Agents。

工作原理

self_hosted 环境充当一个工作队列。您运行一个 environment worker(环境工作进程),这是在您自己的基础设施上为该队列提供服务的进程:

  1. 您创建一个以该环境为目标的会话。Anthropic 将该会话作为工作项加入队列。
  2. 您的工作进程认领该工作项,并下载智能体的技能和会话的记忆存储。
  3. Claude 在 Anthropic 一侧运行并请求工具调用。您的工作进程在本地运行每个调用,并将结果回传。

工具的输入和输出仍会流向 Anthropic 一侧的 Managed Agents,以便模型接收结果并决定下一步操作。技能和记忆存储由 Anthropic 存储。您的沙箱会为该会话保存一份副本。要了解会话的各个部分分别在哪里运行,请参阅沙箱能做什么、不能做什么。

自托管沙箱支持 Managed Agents 中可用的所有 Claude 模型。您在智能体上配置模型,而不是在环境上。

ant CLI 以及 Python、TypeScript 和 Go SDK 都附带预构建的工作进程。Cloudflare、Daytona 和 Modal 等沙箱提供商也发布了各自的平台指南。

快速入门

本快速入门使用 ant CLI 运行一个常驻工作进程,向其发送一个会话,并确认智能体的工具调用在您的主机上运行。

前提条件

  • 一个智能体: 如果您还没有,请先完成开始使用 Claude Managed Agents,并记下智能体 ID。
  • 一台 Linux 或 macOS 主机: 主机需要在该确切路径下有 /bin/bash。worker 只需要出站 HTTPS。
  • 一个 Claude API 密钥: 您在自己的机器上使用它来创建会话和读取队列统计信息。不要将它放在 worker 主机上,因为智能体的工具调用可能会读取到它。
  • 您自己机器上的 ant CLI 或 SDK: 本快速入门中的统计和会话步骤在您自己的机器上运行,而不是在 worker 主机上。请按照运行您的第一个会话中在 worker 主机上安装 CLI 的相同方式安装 CLI,或者按照 SDK、CLI 和库中的说明安装 SDK。

运行您的第一个会话

创建自托管环境

在 Claude Console 中,前往环境页面(platform.claude.com/environments),点击创建环境,然后在托管下选择自托管。

或者通过 API:

示例代码
curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "self-hosted",
    "config": {"type": "self_hosted"}
  }'
示例代码
ant apply environment.yaml
示例代码
# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: self-hosted
config:
  type: self_hosted
示例代码
client = anthropic.Anthropic()

environment = client.beta.environments.create(
    name="self-hosted", config={"type": "self_hosted"}
)
print(environment.id)
示例代码
const client = new Anthropic();

const environment = await client.beta.environments.create({
  name: "self-hosted",
  config: { type: "self_hosted" }
});
console.log(environment.id);
示例代码
using Anthropic.Models.Beta.Environments;

var client = new AnthropicClient();

var environment = await client.Beta.Environments.Create(
    new EnvironmentCreateParams
    {
        Name = "self-hosted",
        Config = new BetaSelfHostedConfigParams(),
    }
);
Console.WriteLine(environment.ID);
示例代码
client := anthropic.NewClient()

environment, err := client.Beta.Environments.New(context.Background(), anthropic.BetaEnvironmentNewParams{
	Name: "self-hosted",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfSelfHosted: &anthropic.BetaSelfHostedConfigParams{},
	},
})
if err != nil {
	panic(err)
}
fmt.Println(environment.ID)
示例代码
import com.anthropic.models.beta.environments.BetaSelfHostedConfigParams;
import com.anthropic.models.beta.environments.EnvironmentCreateParams;

void main() {
    var client = AnthropicOkHttpClient.fromEnv();

    var environment = client.beta().environments().create(
        EnvironmentCreateParams.builder()
            .name("self-hosted")
            .config(BetaSelfHostedConfigParams.builder().build())
            .build()
    );
    IO.println(environment.id());
}
示例代码
$client = new Client();

$environment = $client->beta->environments->create(
    name: 'self-hosted',
    config: ['type' => 'self_hosted'],
);
echo $environment->id, PHP_EOL;
示例代码
client = Anthropic::Client.new

environment = client.beta.environments.create(
  name: "self-hosted",
  config: {type: :self_hosted}
)
puts environment.id

生成环境密钥

在 Console 中,打开该环境并点击生成环境密钥。环境密钥用于向其队列验证 worker 的身份。即使是通过 API 创建的环境,也只能在 Console 中生成环境密钥。

在 worker 主机上导出环境 ID 和密钥:

示例代码
export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
export ANTHROPIC_ENVIRONMENT_ID="env_..."

安装 ant CLI

在 worker 主机上运行以下命令。

Homebrew (macOS)

示例代码
brew install anthropics/tap/ant

curl (Linux/WSL)

对于 Linux 环境,请直接下载发布版二进制文件。

示例代码
VERSION=2.9.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
  x86_64) ARCH=amd64 ;;
  aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

您可以在 GitHub 发布页面上找到所有发布版本。

go install

您也可以使用 go install 从源代码安装 CLI,这需要 Go 1.26.10 或更高版本。

示例代码
go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latest

go install 会将二进制文件放置在 $(go env GOPATH)/bin 中。如果该目录尚未添加到您的 PATH 中,请将其添加进去:

示例代码
export PATH="$PATH:$(go env GOPATH)/bin"

检查安装情况:

示例代码
ant --version

启动 worker

创建工作目录,然后将 --workdir 设置为该目录来启动 worker。如果不使用该标志,worker 将使用当前目录。

Linux

传入 /workspace 以与系统默认值保持一致。

示例代码
sudo mkdir -p /workspace && sudo chown "$USER" /workspace
ant beta:worker poll --workdir /workspace

macOS

根卷是只读的,因此 mkdir 无法创建 /workspace。请改用您主目录中的某个目录。如果智能体使用 skills,请按照沙箱文件系统中的说明,将此目录的完整路径(echo ~/workspace 会打印该路径)添加到其系统提示中。

示例代码
mkdir -p ~/workspace
ant beta:worker poll --workdir ~/workspace

worker 会读取您导出的两个变量,并持续轮询,直到您停止它。

验证 worker 已连接

在您自己的机器上,将 ANTHROPIC_API_KEY 设置为您的 Claude API 密钥(而不是环境密钥),并将 ANTHROPIC_ENVIRONMENT_ID (python, ruby: environment_id; typescript, java, csharp: environmentId; go: environmentID; php: $environmentId) 设置为环境 ID。确认 workers_polling (java, php: workersPolling; csharp, go: WorkersPolling) 至少为 1:

示例代码
curl -sS --fail-with-body "https://api.anthropic.com/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/stats" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: managed-agents-2026-04-01"
示例代码
ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"
示例代码
client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(environment_id)
print(f"workers_polling={stats.workers_polling}")
示例代码
const client = new Anthropic();

const stats = await client.beta.environments.work.stats(environmentId);

console.log(`workers_polling=${stats.workers_polling}`);
示例代码
var client = new AnthropicClient();

var stats = await client.Beta.Environments.Work.Stats(environmentId);

Console.WriteLine($"workers_polling={stats.WorkersPolling}");
示例代码
client := anthropic.NewClient()

stats, err := client.Beta.Environments.Work.Stats(
	context.Background(),
	environmentID,
	anthropic.BetaEnvironmentWorkStatsParams{},
)
if err != nil {
	panic(err)
}

fmt.Printf("workers_polling=%d\n", stats.WorkersPolling)
示例代码
var client = AnthropicOkHttpClient.fromEnv();

var stats = client.beta().environments().work().stats(environmentId);

IO.println("workers_polling=" + stats.workersPolling().orElse(null));
示例代码
$client = new Client();

$stats = $client->beta->environments->work->stats($environmentId);

printf("workers_polling=%d\n", $stats->workersPolling);
示例代码
client = Anthropic::Client.new

stats = client.beta.environments.work.stats(environment_id)

puts "workers_polling=#{stats.workers_polling}"

如果 workers_polling (java, php: workersPolling; csharp, go: WorkersPolling) 一直为 0,请参阅故障排除。

启动会话

将 AGENT_ID (python, ruby: agent_id; typescript, java, csharp: agentId; go: agentID; php: $agentId) 设置为您的智能体 ID。创建一个以该环境为目标的会话,然后向其发送一个任务:

示例代码
# 创建会话
curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "agent": "'"$AGENT_ID"'",
    "environment_id": "'"$ANTHROPIC_ENVIRONMENT_ID"'"
  }'

# 向其发送任务:SESSION_ID 是创建响应中返回的 ID
curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {
            "type": "text",
            "text": "Write the output of \"uname -a\" to hello.txt in your working directory."
          }
        ]
      }
    ]
  }'
示例代码
# 创建会话
ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

# 向其发送任务:SESSION_ID 是创建响应中返回的 ID
ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: Write the output of "uname -a" to hello.txt in your working directory.
YAML
示例代码
session = client.beta.sessions.create(
    agent=agent_id,
    environment_id=environment_id,
)

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": 'Write the output of "uname -a" to hello.txt in your working directory.',
                },
            ],
        },
    ],
)
示例代码
const session = await client.beta.sessions.create({
  agent: agentId,
  environment_id: environmentId
});

await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [
        {
          type: "text",
          text: 'Write the output of "uname -a" to hello.txt in your working directory.'
        }
      ]
    }
  ]
});
示例代码
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agentId,
    EnvironmentID = environmentId,
});

await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Content =
            [
                new BetaManagedAgentsTextBlock
                {
                    Text = "Write the output of \"uname -a\" to hello.txt in your working directory.",
                },
            ],
        },
    ],
});
示例代码
session, err := client.Beta.Sessions.New(context.Background(), anthropic.BetaSessionNewParams{
	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agentID)},
	EnvironmentID: environmentID,
})
if err != nil {
	panic(err)
}

_, err = client.Beta.Sessions.Events.Send(context.Background(), session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
					Text: "Write the output of \"uname -a\" to hello.txt in your working directory.",
				},
			}},
		},
	}},
})
if err != nil {
	panic(err)
}
示例代码
var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(agentId)
    .environmentId(environmentId)
    .build());

client.beta().sessions().events().send(
    session.id(),
    EventSendParams.builder()
        .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
            .addTextContent("Write the output of \"uname -a\" to hello.txt in your working directory.")
            .build())
        .build());
示例代码
$session = $client->beta->sessions->create(
    agent: $agentId,
    environmentID: $environmentId,
);

$client->beta->sessions->events->send(
    $session->id,
    events: [
        [
            'type' => 'user.message',
            'content' => [['type' => 'text', 'text' => 'Write the output of "uname -a" to hello.txt in your working directory.']],
        ],
    ],
);
示例代码
session = client.beta.sessions.create(
  agent: agent_id,
  environment_id: environment_id
)

client.beta.sessions.events.send_(
  session.id,
  events: [
    {
      type: :"user.message",
      content: [{type: :text, text: 'Write the output of "uname -a" to hello.txt in your working directory.'}]
    }
  ]
)

会话会在环境的队列中等待,直到有 worker 认领它。如果没有连接任何 worker,会话将保持排队状态,而不会失败。

确认工具在您的主机上运行

在 worker 主机上,读取智能体写入的文件:

Linux

示例代码
cat /workspace/hello.txt

macOS

示例代码
cat ~/workspace/hello.txt

该文件描述的是您自己主机的内核,因此智能体的工具调用是在那里运行的。要实时跟踪智能体的工作,请参阅会话事件流。

会话资源

自托管沙箱仅支持 memory_store 资源。在自托管环境上包含 file 或 github_repository 资源的会话会被拒绝,并返回 400 错误:

示例代码
Environment env_... is a self-hosted environment. `resources` are not supported with self-hosted environments.

以自托管环境为目标的部署遵循相同的规则。要为会话提供其自己的输入文件,请参阅为会话暂存文件。

自托管沙箱与 MCP 隧道

自托管控制的是智能体代码在哪里运行。MCP 隧道控制的是 Anthropic 如何访问您网络中的 MCP 服务器。两者相互独立:

  • 在 Anthropic 云沙箱中的会话可以通过隧道访问私有 MCP 服务器。例如,私有 MCP 服务器可能部署在您防火墙后的数据库或内部 API 前面。
  • 自托管会话可以使用经隧道连接的 MCP 服务器或公共 MCP 服务器。

当您希望执行和工具访问都保留在您的边界内时,请同时使用两者。要跳过隧道,请将 MCP 服务器封装为自定义工具,由您的工作进程提供服务。

平台指南

自托管沙箱的各个页面介绍了如何在任何沙箱平台上构建工作进程。以下提供商也发布了各自平台的指南:

后续步骤

部署工作进程

运行 SDK 工作进程、通过 webhook 触发工作进程,或为每个会话提供独立的沙箱。

监控和故障排除

读取队列深度、干净地停止会话和工作进程,并修复常见故障。

可用性

自托管沙箱在所有模型上处于 beta 阶段。

API 支持

Managed Agents

  • 可用性:可用

所需的 beta 请求头

Beta 请求头概览

Beta 请求头让您可以在实验性功能和新模型能力成为标准 API 的一部分之前访问它们。

  • managed-agents-2026-04-01

数据处理

数据处理概览

项目零数据保留HIPAA
状态不具备资格不具备资格
详细信息不具备 ZDR 资格,自托管 Managed Agents 除外。会话是有状态的资源;对话记录会一直保留,直到您将其删除。 了解更多不具备 HIPAA 资格。适用于所有 Managed Agents 子功能。

适用的端点:

  • /v1/agents
  • /v1/sessions
  • /v1/environments
文档内容持续同步更新