---
title: 自行託管沙箱
url: https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes
description: 在自行託管的沙箱中執行 Claude Managed Agents 工作階段，將工具執行、檔案和網路出口流量保留在您自己的基礎架構中。
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

自行託管沙箱會將代理的工具執行從 Anthropic 管理的雲端沙箱移至您所控制的基礎架構中，而 Anthropic 則持續執行代理本身。若要了解這代表什麼意義，並判斷它是否適合您的代理，請參閱[選擇代理環境](https://platform.claude.com/docs/zh-TW/managed-agents/choosing-an-environment)。

## 運作方式

`self_hosted` 環境的作用就像一個工作佇列。您需要執行一個 **environment worker**（環境工作程序），這是在您自己的基礎架構上為該佇列提供服務的處理程序：

1. 您建立一個以該環境為目標的[工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/sessions)。Anthropic 會將該工作階段作為工作項目加入佇列。
2. 您的工作程序認領該工作項目，並下載代理的[技能](https://platform.claude.com/docs/zh-TW/managed-agents/skills)和工作階段的[記憶體儲存區](https://platform.claude.com/docs/zh-TW/managed-agents/memory)。
3. Claude 在 Anthropic 端執行並請求工具呼叫。您的工作程序在本機執行每個呼叫，並將結果回傳。

工具的輸入和輸出仍會流向 Anthropic 的控制平面，讓模型能夠看到結果並決定下一步該做什麼。Anthropic 會儲存技能和記憶體儲存區。您的沙箱會為該工作階段保留一份副本。如需完整的資料流邊界，請參閱[安全模型](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-security)。

自行託管沙箱支援 Managed Agents 中提供的所有 Claude 模型。模型是在代理上設定，而非在環境上設定。

`ant` CLI 以及 Python、TypeScript 和 Go SDK 都隨附預先建置的工作程序。Cloudflare、Daytona 和 Modal 等沙箱供應商也發布了各自的[平台指南](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes#platform-guides)。

## 快速入門

本快速入門使用 `ant` CLI 執行一個持續運作的工作程序，向其傳送一個工作階段，並確認代理的工具呼叫是在您的主機上執行。

### 先決條件

* **一個代理：** 如果您還沒有代理，請先完成[開始使用 Claude Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/quickstart)，並記下代理 ID。
* **一台 Linux 主機：** 主機需要在確切的 `/bin/bash` 路徑上有 bash。工作程序只需要對外的 HTTPS 連線。
* **一個 Claude API 金鑰：** 您會在自己的電腦上使用它來建立工作階段和讀取佇列統計資料。請勿將其放在工作程序主機上，因為代理的工具呼叫可能會讀取到它。
* **在您自己的電腦上安裝 `ant` CLI 或 SDK：** 本快速入門中的統計資料和工作階段步驟是在您的電腦上執行，而非在工作程序主機上。請以與工作程序的[安裝步驟](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes#run-your-first-session)相同的方式安裝 CLI，或安裝 [SDK](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/overview)。

<Note>
  在 [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws) 上，工作程序使用 AWS IAM（SigV4）或[在 AWS Console 中產生的 API 金鑰](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws#api-key-authentication)進行驗證，而非使用環境金鑰。請將 [`AnthropicSelfHostedEnvironmentAccess`](https://platform.claude.com/docs/zh-TW/api/claude-platform-on-aws-iam-actions#managed-policies) 受管政策附加到執行工作程序的 IAM 主體。在 Claude Console 中產生的環境金鑰無法用於 Claude Platform on AWS 端點。
</Note>

### 執行您的第一個工作階段

<Steps>
  <Step title="建立自行託管環境">
    在 Claude Console 中，前往 [Environments](https://platform.claude.com/environments) 頁面（`platform.claude.com/environments`），點擊 **Create environment**，並在 **Hosting** 下選擇 **Self-hosted**。

    或透過 API：

    <CodeGroup defaultLanguage="CLI">
      ```bash cURL
      curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2023-06-01" \
        -H "anthropic-beta: managed-agents-2026-04-01" \
        -H "content-type: application/json" \
        -d '{
          "name": "self-hosted",
          "config": {"type": "self_hosted"}
        }'
      ```

      <CodeGroupItem>
        ```bash CLI
        ant apply environment.yaml
        ```

        <File filename="environment.yaml">
          ```yaml
          # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
          name: self-hosted
          config:
            type: self_hosted
          ```
        </File>
      </CodeGroupItem>

      ```python Python
      client = anthropic.Anthropic()

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

      ```typescript TypeScript
      const client = new Anthropic();

      const environment = await client.beta.environments.create({
        name: "self-hosted",
        config: { type: "self_hosted" }
      });
      console.log(environment.id);
      ```

      ```csharp C#
      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);
      ```

      ```go Go
      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)
      ```

      ```java Java
      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());
      }
      ```

      ```php PHP
      $client = new \Anthropic\Client();

      $environment = $client->beta->environments->create(
          name: 'self-hosted',
          config: ['type' => 'self_hosted'],
      );
      echo $environment->id, PHP_EOL;
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      environment = client.beta.environments.create(
        name: "self-hosted",
        config: {type: :self_hosted}
      )
      puts environment.id
      ```
    </CodeGroup>
  </Step>

  <Step title="產生環境金鑰">
    在 Console 中開啟該環境，然後點擊 **Generate environment key**。環境金鑰用於向工作程序的佇列驗證工作程序。即使是透過 API 建立的環境，您也只能在 Console 中產生環境金鑰。

    在工作程序主機上匯出環境 ID 和金鑰：

    ```bash
    export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
    export ANTHROPIC_ENVIRONMENT_ID="env_..."
    ```
  </Step>

  <Step title="安裝 ant CLI">
    在工作程序主機上執行此操作。

    <Tabs>
      <Tab title="curl (Linux/WSL)">
        對於 Linux 環境，請直接下載發行版本的二進位檔。

        ```bash
        VERSION=1.42.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 發行頁面](https://github.com/anthropics/anthropic-cli/releases)上找到所有發行版本。
      </Tab>

      <Tab title="Homebrew (macOS)">
        ```bash
        brew install anthropics/tap/ant
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="啟動工作程序">
    建立工作目錄，然後啟動工作程序。`--workdir` 預設為目前目錄，因此請傳入 `/workspace` 以符合系統預設值。

    ```bash
    sudo mkdir -p /workspace && sudo chown "$USER" /workspace
    ant beta:worker poll --workdir /workspace
    ```

    工作程序會讀取您匯出的兩個變數，並持續輪詢直到您停止它。
  </Step>

  <Step title="確認工作程序已連線">
    在您自己的電腦上，將 `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：

    <CodeGroup>
      ```bash cURL
      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: 2023-06-01" \
        -H "anthropic-beta: managed-agents-2026-04-01"
      ```

      ```bash CLI
      ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"
      ```

      ```python Python
      client = anthropic.Anthropic()

      stats = client.beta.environments.work.stats(environment_id)
      print(f"workers_polling={stats.workers_polling}")
      ```

      ```typescript TypeScript
      const client = new Anthropic();

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

      console.log(`workers_polling=${stats.workers_polling}`);
      ```

      ```csharp C#
      var client = new AnthropicClient();

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

      Console.WriteLine($"workers_polling={stats.WorkersPolling}");
      ```

      ```go Go
      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)
      ```

      ```java Java
      var client = AnthropicOkHttpClient.fromEnv();

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

      IO.println("workers_polling=" + stats.workersPolling().orElse(null));
      ```

      ```php PHP
      $client = new Client();

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

      printf("workers_polling=%d\n", $stats->workersPolling);
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

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

      puts "workers_polling=#{stats.workers_polling}"
      ```
    </CodeGroup>

    如果 `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) 一直維持為 0，請參閱[疑難排解](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations#troubleshooting)。
  </Step>

  <Step title="啟動工作階段">
    將 `AGENT_ID` (python, ruby: `agent_id`; typescript, java, csharp: `agentId`; go: `agentID`; php: `$agentId`) 設定為您代理的 ID。建立一個以該環境為目標的工作階段，然後向其傳送一項任務：

    <CodeGroup>
      ```bash cURL
      SESSION_ID=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2023-06-01" \
        -H "anthropic-beta: managed-agents-2026-04-01" \
        -H "content-type: application/json" \
        -d '{
          "agent": "'"$AGENT_ID"'",
          "environment_id": "'"$ANTHROPIC_ENVIRONMENT_ID"'"
        }' | jq -er '.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: 2023-06-01" \
        -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."
                }
              ]
            }
          ]
        }'
      ```

      ```bash CLI
      SESSION_ID=$(ant beta:sessions create \
        --agent "$AGENT_ID" \
        --environment-id "$ANTHROPIC_ENVIRONMENT_ID" \
        --transform id --raw-output)

      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
      ```

      ```python Python
      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.',
                      },
                  ],
              },
          ],
      )
      ```

      ```typescript TypeScript
      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.'
              }
            ]
          }
        ]
      });
      ```

      ```csharp C#
      var session = await client.Beta.Sessions.Create(new()
      {
          Agent = agentId,
          EnvironmentID = environmentId,
      });

      await client.Beta.Sessions.Events.Send(session.ID, new()
      {
          Events =
          [
              new BetaManagedAgentsUserMessageEventParams
              {
                  Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
                  Content =
                  [
                      new BetaManagedAgentsTextBlock
                      {
                          Type = BetaManagedAgentsTextBlockType.Text,
                          Text = "Write the output of \"uname -a\" to hello.txt in your working directory.",
                      },
                  ],
              },
          ],
      });
      ```

      ```go Go
      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{
      			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
      			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
      				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
      					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
      					Text: "Write the output of \"uname -a\" to hello.txt in your working directory.",
      				},
      			}},
      		},
      	}},
      })
      if err != nil {
      	panic(err)
      }
      ```

      ```java Java
      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()
                  .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                  .addTextContent("Write the output of \"uname -a\" to hello.txt in your working directory.")
                  .build())
              .build());
      ```

      ```php PHP
      $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.']],
              ],
          ],
      );
      ```

      ```ruby Ruby
      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.'}]
          }
        ]
      )
      ```
    </CodeGroup>

    工作階段會在環境的佇列中等待，直到有工作程序認領它。如果沒有連線的工作程序，工作階段會保持在佇列中，而不會失敗。
  </Step>

  <Step title="確認工具在您的主機上執行">
    在工作程序主機上，讀取代理寫入的檔案：

    ```bash
    cat /workspace/hello.txt
    ```

    該檔案描述的是您自己主機的核心，因此代理的工具呼叫是在那裡執行的。若要即時追蹤代理的工作，請參閱[工作階段事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming)。
  </Step>
</Steps>

## 工作階段資源

自行託管沙箱僅支援 `memory_store` 資源。在自行託管環境上包含 `file` 或 `github_repository` 資源的工作階段會被拒絕，並傳回 400 錯誤：

```text wrap
Environment env_... is a self-hosted environment. `resources` are not supported with self-hosted environments.
```

以自行託管環境為目標的[部署](https://platform.claude.com/docs/zh-TW/managed-agents/scheduled-deployments)也遵循相同規則。若要為工作階段提供其專屬的輸入檔案，請參閱[為工作階段暫存檔案](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers#stage-files-for-a-session)。

## 自行託管沙箱與 MCP 通道

自行託管控制的是*代理程式碼在何處執行*。[MCP 通道](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/overview)控制的是 *Anthropic 如何存取您網路中的 MCP 伺服器*。兩者彼此獨立：

* 在 Anthropic 雲端沙箱中的工作階段可以透過通道連線到私有 MCP 伺服器。例如，私有 MCP 伺服器可能位於您防火牆後方的資料庫或內部 API 前端。
* 自行託管的工作階段可以使用透過通道連線的 MCP 伺服器或公開的 MCP 伺服器。

當您希望執行和工具存取都保留在您的邊界內時，請同時使用兩者。若要略過通道，請[將 MCP 伺服器包裝為自訂工具](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools)，由您的工作程序提供服務。

## 平台指南

這些頁面說明如何在任何沙箱平台上建置工作程序。另外也提供特定平台的指南：

* [AWS Lambda MicroVMs](https://docs.aws.amazon.com/lambda/latest/dg/microvms-integrations-claude-managed-agents.html)
* [Blaxel](https://docs.blaxel.ai/Tutorials/Claude-Managed-Agents)
* [Cloudflare](https://developers.cloudflare.com/sandbox/claude-managed-agents/)
* [Daytona](https://www.daytona.io/docs/en/guides/claude/claude-managed-agents)
* [E2B](https://e2b.dev/docs/agents/claude-managed-agents)
* [Fly.io](https://docs.sprites.dev/integrations/claude-managed-agents/)
* [GKE Agent Sandbox](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/tree/main/ai-ml/anthropic-agent-sandbox)
* [Modal](https://github.com/modal-labs/claude-managed-agents-modal-sandbox)
* [Namespace](https://namespace.so/docs/integrations/claude)
* [Superserve](https://docs.superserve.ai/integrations/managed-agents/claude-managed-agents)
* [Vercel](https://vercel.com/kb/guide/run-claude-managed-agent-tools-with-vercel-sandbox)

## 後續步驟

<CardGroup cols={2}>
  <Card title="部署工作程序" icon="play" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers">
    執行 SDK 工作程序、從 webhook 觸發工作程序，或為每個工作階段提供專屬的沙箱。
  </Card>

  <Card title="記憶體儲存區" icon="brain" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory">
    準備主機、設定同步，以及處理唯讀儲存區和衝突。
  </Card>

  <Card title="自訂工具與 MCP 伺服器" icon="tool" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-custom-tools">
    從工作程序提供您自己的工具，包括來自您網路內 MCP 伺服器的工具。
  </Card>

  <Card title="監控與疑難排解" icon="lightning" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations">
    讀取佇列深度、乾淨地停止工作階段和工作程序，以及修正常見的失敗問題。
  </Card>

  <Card title="工作程序參考" icon="book" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference">
    CLI 旗標、環境變數、檔案系統路徑和 SDK 輔助選項。
  </Card>

  <Card title="安全模型" icon="lock" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-security">
    自行託管沙箱環境的共同責任模型。
  </Card>
</CardGroup>