docs: document sandbox environment variables

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,38 +92,28 @@ 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
 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

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"

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 <sandbox-name> 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 <name> <command>` 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 <sandbox-name> bash -c "your-command"
-```
-
-To verify the variable is set, open a shell in the sandbox:
-
-```console
-$ sbx exec -it <sandbox-name> 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?
 

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 <sandbox-name> 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/):