> ## 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.

# Manage environments

The `env` command group manages AgentKit environment resources. The current public workflow is for Claude self-host sandbox projects: create the sandbox Tool with `sandbox`, then create the Runtime bound to that Tool with `env create`. `environment` is an alias of `env`.

<Warning>
  `env create` provisions a cloud Runtime and may use or create a runtime IAM role, which can incur charges while the resources exist. Confirm that the Tool, Runtime, region, and Anthropic environment settings in `.agentkit/sandbox.yaml` belong to the target project before running it.
</Warning>

## Command overview

| Subcommand | Description |
| - | - |
| `create` | Create the Runtime for a Claude self-host sandbox and persist local environment state. |
| `status` | Query Tool and Runtime status for the current self-host environment. |

## env create

Create the Runtime for the current Claude self-host sandbox project. The command requires `.agentkit/sandbox.yaml` generated by `agentkit sandbox init -t self-host` in the current directory, with `project_type` set to `self-host`. By default it reads `self_host.sandbox.id` as the existing Tool ID; pass `--tool-id` to override it.

During creation, the CLI writes progress state to `.agentkit/environment.yaml`. After a successful create, it prints the environment state as JSON. If local state already contains a Runtime ID, the command stops unless `--force-new` is passed explicitly.

When creating the Runtime, the CLI injects `ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_ENVIRONMENT_KEY`, and `AGENTKIT_TOOL_ID` from `self_host.environment` and the Tool ID. Replace the generated placeholders with real values first; this workflow does not require an additional dotenv file.

| Flag / Argument | Description | Default |
| - | - | - |
| `--force-new` | Create a new Runtime even when `.agentkit/environment.yaml` already records one. | `false` |
| `--tool-id <id>` | Override `self_host.sandbox.id` from `.agentkit/sandbox.yaml`. | `self_host.sandbox.id` |

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

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

## env status

Refresh and print the current self-host environment status. The command reads the Tool ID and Runtime ID from `.agentkit/environment.yaml`, then queries the latest cloud status. Local environment status becomes `ready` only when both the Tool and Runtime are `Ready`.

| Flag / Argument | Description | Default |
| - | - | - |
| *(no options)* | This subcommand takes no options. | — |

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

## State File

`.agentkit/environment.yaml` is the current project's local environment state file, written by `env create` and `env status`. It records the environment type, overall status, Tool ID, Runtime ID, image URLs, error message, and timestamps. Command output does not include the `env` field.

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