跳转到主要内容
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.
Before you start, make sure your Volcengine access keys are configured — the VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY environment variables.
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:
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:
--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:
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:
4

Preview the app you are building

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

Clean up the session

When you are done, stop and delete the session; use --all to clear every session on the sandbox tool:
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.
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:
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:

​
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.
最后修改于 2026年9月19日