diff --git a/content/guides/claude-code-sandbox-model-runner.md b/content/guides/claude-code-sandbox-model-runner.md index 8b6e58d7e643..c65d429da32a 100644 --- a/content/guides/claude-code-sandbox-model-runner.md +++ b/content/guides/claude-code-sandbox-model-runner.md @@ -52,7 +52,7 @@ Before you start, make sure you have: - [Docker Desktop](../get-started/get-docker.md) or Docker Engine installed - [Docker Model Runner enabled](../manuals/ai/model-runner/get-started.md#enable-docker-model-runner) -- [Docker Sandboxes (`sbx`) installed and signed in](../manuals/ai/sandboxes/get-started.md#install-and-sign-in) +- [Docker Sandboxes (`sbx`) version 0.39.0 or later installed and signed in](../manuals/ai/sandboxes/get-started.md#install-and-sign-in) If you use Docker Desktop, turn on TCP access in **Settings** > **AI**, or run: @@ -92,17 +92,19 @@ For background on host access from sandboxes, see ## Step 3: Create a Claude Code sandbox -From your project directory, create a sandbox without launching the agent: +From your project directory, create a sandbox without launching the agent. Set +`ANTHROPIC_BASE_URL` so Claude Code uses Docker Model Runner whenever the +sandbox starts: ```console $ cd ~/my-project -$ sbx create claude --name claude-dmr . +$ sbx create --name claude-dmr \ + -e ANTHROPIC_BASE_URL=http://host.docker.internal:12434 \ + claude . ``` -`sbx run` would also work, but it launches Claude Code immediately. Without -`ANTHROPIC_BASE_URL` set, Claude Code points at `api.anthropic.com` and -either prompts for OAuth or errors out before you can fix the endpoint. -Creating the sandbox first lets you write the local endpoint into it before +`sbx run` would also work, but it launches Claude Code immediately. Creating +the sandbox first lets you confirm the variable and test connectivity before the agent starts. You don't need to set an Anthropic API key or run `sbx secret set @@ -110,20 +112,8 @@ anthropic`. Docker Model Runner doesn't authenticate the local endpoint, and the sandbox proxy only injects credentials for requests bound for `api.anthropic.com`. See [Credentials](../manuals/ai/sandboxes/security/credentials.md) for the full -list of services the proxy authenticates. - -## Step 4: Set the local endpoint inside the sandbox - -Append `ANTHROPIC_BASE_URL` to the sandbox's persistent environment file so -Claude Code reads it on every launch: - -```console -$ sbx exec -d claude-dmr bash -c "echo 'export ANTHROPIC_BASE_URL=http://host.docker.internal:12434' >> /etc/sandbox-persistent.sh" -``` - -The `bash -c` wrapper ensures the `>>` redirect runs inside the sandbox, not -on your host. For details on this approach, see -[How do I set custom environment variables inside a sandbox?](../manuals/ai/sandboxes/faq.md#how-do-i-set-custom-environment-variables-inside-a-sandbox). +list of services the proxy authenticates. For more ways to set variables, see +[Set environment variables](../manuals/ai/sandboxes/usage.md#set-environment-variables). To confirm the variable is set, open a shell in the sandbox: @@ -133,7 +123,7 @@ $ echo $ANTHROPIC_BASE_URL http://host.docker.internal:12434 ``` -## Step 5: Verify connectivity to Docker Model Runner +## Step 4: Verify connectivity to Docker Model Runner Still inside the sandbox shell, send a test request to the host endpoint: @@ -152,7 +142,7 @@ Type `exit` to leave the shell. For more details about the request format, see the [Anthropic-compatible API reference](../manuals/ai/model-runner/api-reference.md#anthropic-compatible-api). -## Step 6: Launch Claude Code with the local model +## Step 5: Launch Claude Code with the local model Run Claude Code in the sandbox and pass the model flag through to the agent: @@ -161,11 +151,10 @@ $ sbx run claude-dmr -- --model ai/devstral-small-2 ``` Everything after `--` is forwarded to the Claude Code CLI. Because -`ANTHROPIC_BASE_URL` is set in the sandbox's persistent environment, Claude -Code routes requests to Docker Model Runner on your host instead of -`api.anthropic.com`. +`ANTHROPIC_BASE_URL` is stored in the sandbox's environment, Claude Code routes +requests to Docker Model Runner on your host instead of `api.anthropic.com`. -## Step 7: Inspect Claude Code requests +## Step 6: Inspect Claude Code requests To inspect the requests Claude Code sends, run on your host: @@ -176,7 +165,7 @@ $ docker model requests --model ai/devstral-small-2 | jq . This helps you debug prompts, context usage, and compatibility issues without attaching to the sandbox. -## Step 8: Package `gpt-oss` with a larger context window +## Step 7: Package `gpt-oss` with a larger context window `ai/gpt-oss` defaults to a smaller context window than coding-focused models. To use it for repository-scale prompts, package a larger variant on @@ -203,8 +192,7 @@ deleting it: $ sbx stop claude-dmr ``` -To remove the sandbox and everything inside, including the persistent -environment file: +To remove the sandbox and everything inside: ```console $ sbx rm claude-dmr diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md index a3e06446bd68..3f61d4d5a9ab 100644 --- a/content/manuals/ai/sandboxes/customize/kit-examples.md +++ b/content/manuals/ai/sandboxes/customize/kit-examples.md @@ -120,9 +120,10 @@ available in every shell, append the source line to file. It's sourced before every bash invocation — interactive shells and non-interactive ones, including agents started with `sbx run` and commands run with `sbx exec`. Appending here makes the tool available to -the agent regardless of how its shell is launched. The same file is where -you'd set a custom environment variable; see the -[FAQ](../faq.md#how-do-i-set-custom-environment-variables-inside-a-sandbox). +the agent regardless of how its shell is launched. Use +[`environment.variables`](kit-reference.md#environment) for ordinary variables +declared by a kit. To pass variables when creating a sandbox, use +[`-e` or `--env-file`](../usage.md#set-environment-variables). ```yaml {title="nvm/spec.yaml"} schemaVersion: "2" diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 268e29e3ab4e..c2c67cef7d0b 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -89,50 +89,16 @@ $ export SBX_NO_TELEMETRY=1 ## How do I set custom environment variables inside a sandbox? -The [`sbx secret`](/reference/cli/sbx/secret/) command only supports a fixed set -of [services](security/credentials.md#built-in-services) (Anthropic, OpenAI, -GitHub, and others). If your agent needs an environment variable that isn't -tied to a supported service, such as `BRAVE_API_KEY` or a custom internal -token, write it to `/etc/sandbox-persistent.sh` inside the sandbox. This -file is sourced on every shell login, so the variable persists across agent -sessions for the sandbox's lifetime. - -Use `sbx exec` to append the export: - -```console -$ sbx exec -d bash -c "echo 'export BRAVE_API_KEY=your_key' >> /etc/sandbox-persistent.sh" -``` - -The `bash -c` wrapper is required so the `>>` redirect runs inside the -sandbox instead of on your host. - -> [!NOTE] -> Unlike `sbx secret`, which injects credentials through a host-side proxy -> without exposing them to the agent, this approach stores the value inside -> the sandbox. The agent process can read it directly. Only use this for -> credentials where proxy-based injection isn't available. - -Variables in `/etc/sandbox-persistent.sh` are sourced automatically for -interactive sessions and for agents started with `sbx run`. - -A variable only takes effect for sessions and agents started *after* it's -added. If an agent is already running when you append to the file, restart -it (or stop and start the sandbox) to pick up the new value. - -Running commands directly with `sbx exec ` does not invoke -a shell, so the persistent environment file is not sourced. Wrap the -command in `bash -c` to load the environment: - -```console -$ sbx exec bash -c "your-command" -``` - -To verify the variable is set, open a shell in the sandbox: - -```console -$ sbx exec -it bash -$ echo $BRAVE_API_KEY -``` +Starting with `sbx` version 0.39.0, use `-e`/`--env` or `--env-file` with +`sbx run` and `sbx create`. See +[Set environment variables](usage.md#set-environment-variables) for syntax, +precedence rules, persistent configuration for an existing sandbox, and +guidance for credentials. + +Variables in `/etc/sandbox-persistent.sh` are available to interactive sessions +and agents started with `sbx run`. A variable only takes effect for sessions +and agents started after it's added. Restart a running agent, or stop and start +the sandbox, to pick up the new value. ## Why do agents run without approval prompts? diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index ef4286e39b6b..8cdd1ca96ddf 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -96,6 +96,68 @@ Unlike `run`, `create` requires an explicit workspace path. Attach later with $ sbx run --name my-project ``` +## Set environment variables + +> [!NOTE] +> The `-e`/`--env` and `--env-file` flags require `sbx` version 0.39.0 or +> later. + +Pass `-e` or `--env` to `sbx run` or `sbx create` to set an environment +variable in the sandbox: + +```console +$ sbx run -e LOG_LEVEL=debug claude +``` + +Specify a variable name without a value to copy its value from the host +environment: + +```console +$ export API_URL=https://api.example.com +$ sbx run -e API_URL claude +``` + +To load multiple variables, pass one or more environment files: + +```console +$ sbx create --name my-project --env-file .env.sandbox claude . +``` + +The flags follow `docker run` precedence rules. Values passed with `-e` +override values from environment files. When you pass multiple environment +files, a value in a later file overrides the same variable in an earlier file. + +When either command creates a sandbox, the variables are stored with the +sandbox. They are also available to the agent session started by `sbx run`. +When `sbx run` re-attaches to an existing sandbox, the variables apply to that +agent session without changing the sandbox's stored environment. To set +variables for one command instead, use `sbx exec -e` or +`sbx exec --env-file`. + +To persist a variable across future sessions of an existing sandbox, append an +export to `/etc/sandbox-persistent.sh`: + +```console +$ sbx exec -d bash -c "echo 'export INTERNAL_API_URL=https://api.example.com' >> /etc/sandbox-persistent.sh" +``` + +The `bash -c` wrapper ensures the `>>` redirect runs inside the sandbox instead +of on your host. The file is sourced when Bash starts inside the sandbox, +including for interactive sessions and agents started with `sbx run`. A command +passed directly to `sbx exec` doesn't start a shell. Wrap that command in +`bash -c` if it needs variables from the persistent environment file. + +A variable added to the file only takes effect for sessions and agents started +afterward. Restart a running agent, or stop and start the sandbox, to pick up +the new value. + +Environment variables are readable by processes inside the sandbox. For API +keys and other credentials, use [`sbx secret set`](security/credentials.md#store-a-secret) +for a supported service or the experimental +[`sbx secret set-custom`](security/credentials.md#custom-secrets) for a +credential sent to known hosts. The host-side proxy can then inject the real +value without exposing it to the agent. + ## Run commands inside a sandbox To get a shell inside a running sandbox, use [`sbx exec`](/reference/cli/sbx/exec/):