> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理环境

`env` 命令组用于管理 AgentKit 环境资源。当前公开能力面向 Claude 自托管沙箱项目：先用 `sandbox` 命令创建沙箱 Tool，再用 `env create` 创建与该 Tool 绑定的 Runtime。`environment` 是 `env` 的等价别名。

<Warning>
  `env create` 会创建云端 Runtime，并可能使用或创建运行时 IAM 角色，资源存续期间可能产生费用。执行前确认 `.agentkit/sandbox.yaml` 中的 Tool、Runtime、区域和 Anthropic 环境配置都属于目标项目。
</Warning>

## 命令总览

| 子命令 | 说明 |
| - | - |
| `create` | 为 Claude 自托管沙箱创建 Runtime，并把环境状态写入本地。 |
| `status` | 查询当前自托管环境的 Tool 与 Runtime 状态。 |

## env create

为当前 Claude 自托管沙箱项目创建 Runtime。命令要求当前目录存在由 `agentkit sandbox init -t self-host` 生成的 `.agentkit/sandbox.yaml`，且 `project_type` 为 `self-host`。默认读取 `self_host.sandbox.id` 作为已创建 Tool 的 ID；也可以用 `--tool-id` 显式覆盖。

创建过程中，CLI 会把中间状态写入 `.agentkit/environment.yaml`。创建成功后，命令输出环境状态 JSON；如果本地状态中已经存在 Runtime ID，命令会停止，除非显式传入 `--force-new`。

创建 Runtime 时，CLI 会从 `self_host.environment` 与 Tool ID 注入 `ANTHROPIC_ENVIRONMENT_ID`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_ENVIRONMENT_KEY` 和 `AGENTKIT_TOOL_ID`。生成的占位符必须先替换为真实值；该流程不要求额外创建 dotenv 文件。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--force-new` | 即使 `.agentkit/environment.yaml` 已记录 Runtime，也创建新的 Runtime。 | `false` |
| `--tool-id <id>` | 覆盖 `.agentkit/sandbox.yaml` 中的 `self_host.sandbox.id`。 | `self_host.sandbox.id` |

```bash lines theme={null}
agentkit env create

agentkit environment create --tool-id tool-123 --force-new
```

## env status

刷新并输出当前自托管环境的状态。命令读取 `.agentkit/environment.yaml` 中记录的 Tool ID 和 Runtime ID，再查询云端最新状态；只有 Tool 与 Runtime 都处于 `Ready` 时，本地环境状态才会更新为 `ready`。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| *（无选项）* | 该子命令不接受任何选项。 | — |

```bash lines theme={null}
agentkit env status
```

## 状态文件

`.agentkit/environment.yaml` 是当前项目的本地环境状态文件，由 `env create` 和 `env status` 写入。它记录环境类型、整体状态、Tool ID、Runtime ID、镜像地址、错误信息和更新时间；命令输出时不会展示其中的 `env` 字段。

```yaml title=".agentkit/environment.yaml" lines theme={null}
version: 1
type: self-host
status: ready
tool:
  id: tool-123
  status: Ready
runtime:
  id: runtime-123
  status: Ready
  tool_id: tool-123
created_at: "2026-08-25T09:00:00.000Z"
updated_at: "2026-08-25T09:05:00.000Z"
```