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

# Develop apps in a Codex sandbox

An AgentKit sandbox is a cloud `code` tool environment where you can develop applications with a coding agent such as Codex: no local runtime to set up, sessions persist, code transfers both ways, and the app you are building can be viewed through a web preview. For the full options of each sandbox command, see [Use sandboxes](https://docs.veadk.xyz/productions/agentkit-cli/archives/0.46.6/en/commands/sandbox.md).

> [!NOTE]
>
> Before you start, make sure your Volcengine access keys are configured — the `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY` environment variables.

> [!WARNING]
>
> Creating a sandbox provisions cloud compute resources that may incur charges while they exist. Commands in the sandbox can reach files, networks, and credentials available to that environment. Use trusted projects and least-privilege access. Session and sandbox deletion cannot be undone, so download required files before cleanup.

## End-to-end flow

**1. Create a sandbox**

A sandbox is a `code` environment. If the project does not have one yet, create it first:

```bash lines theme={null}
agentkit sandbox create --type code --name dev-sandbox
```

The command returns the sandbox id. Later sandbox commands resolve the `code` sandbox within the project automatically: the sole one is used when there is exactly one, and `--tool-id` is required when there are several (find it with `agentkit sandbox list`). You can also skip this step and add `--auto-create` on the first sandbox command to create one on the fly.

**2. Develop with Codex inside the sandbox**

Open the sandbox session's interactive terminal and run `codex` there to develop:

```bash lines theme={null}
agentkit sandbox shell --session dev --tmux
```

`--session dev` names the session; reuse the same name in later commands to return to the same environment. `--tmux` opens or joins a persistent terminal session so reconnecting after a drop keeps your progress (press Ctrl-] to detach). To bring existing local code into the sandbox, upload it before opening the terminal:

```bash lines theme={null}
agentkit sandbox shell --session dev --src-dir ./my-app --dst-dir my-app
```

The model used by the sandbox's coding agent can be set with `--model-name`, `--model-api-key`, and `--model-provider`.

**3. Transfer files between local and sandbox**

Prefix the remote side with `:`. Upload and download:

```bash lines theme={null}
# Upload
agentkit sandbox cp ./local.txt :/workspace/local.txt --session dev

# Download
agentkit sandbox cp :/workspace/result.json ./result.json --session dev
```

**4. Preview the app you are building**

If you start a web server inside the sandbox, open its web preview to view it:

```bash lines theme={null}
agentkit sandbox web --session dev
```

**5. Clean up the session**

When you are done, stop and delete the session; use `--all` to clear every session on the sandbox tool:

> [!WARNING]
>
> `sandbox rm` removes the session and files that were not persisted elsewhere, but it does not delete the sandbox itself. Back up required files first. When the sandbox is no longer needed, delete the cloud resource separately with `sandbox delete <sandbox-id> -y`.

```bash lines theme={null}
agentkit sandbox rm dev -y
```

> [!WARNING]
>
> `sandbox login` copies a local subscription credential into a remote sandbox session. Use it only with a trusted sandbox and a dedicated session, do not share that session with others, and delete the session when finished.

There are several ways to authenticate Codex inside the sandbox; injecting your local subscription is one of them. If you have logged in locally with `codex login`, you can inject those credentials into the session:

```bash lines theme={null}
agentkit sandbox login --provider codex --session dev
```

The command reads `~/.codex/auth.json` by default; use `--auth-file` or `--codex-home` to point at another source. Switch `--provider` to `claude` to inject your local Claude subscription instead and use Claude Code in the sandbox.

## Scripted execution

Besides the interactive terminal, `sandbox run` executes a single command in the session and prints its output, which is convenient for scripts and automated flows:

```bash lines theme={null}
agentkit sandbox run "codex exec 'add unit tests to the project'" --session dev
```

## Practical guidance

* **Reuse the same session**: keep a fixed `--session` name throughout a development session to preserve the environment and progress; use `agentkit sandbox sessions` to list active sessions and `agentkit sandbox logs <session>` to troubleshoot.
* **Name the sandbox explicitly**: when the project has more than one `code` sandbox, commands require an explicit `--tool-id`; find the target id with `agentkit sandbox list` first.
* **Use `--tmux` for long tasks**: for interactive development, add `--tmux` so a network drop does not lose the session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.