docker · dvdksn · Aug 20, 2026 · Aug 20, 2026
diff --git a/content/guides/claude-code-sandbox-model-runner.md b/content/guides/claude-code-sandbox-model-runner.md
@@ -88,7 +88,7 @@ $ sbx policy allow network localhost:12434
 ```
 
 For background on host access from sandboxes, see
-[Accessing host services from a sandbox](../manuals/ai/sandboxes/workflows.md#accessing-host-services-from-a-sandbox).
+[Accessing host services from a sandbox](../manuals/ai/sandboxes/workflows/development.md#accessing-host-services-from-a-sandbox).
 
 ## Step 3: Create a Claude Code sandbox
 
@@ -111,7 +111,7 @@ 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
+[Credentials](../manuals/ai/sandboxes/configuration/credentials.md) for the full
 list of services the proxy authenticates. For more ways to set variables, see
 [Set environment variables](../manuals/ai/sandboxes/usage.md#set-environment-variables).
 

@@ -40,18 +40,18 @@ jump to the [usage guide](usage.md) for basic commands.
 ## Learn more
 
 - [Agents](agents/) — supported agents and per-agent configuration
+- [Workflows](workflows/) — patterns for Git, local development,
+  authentication, agent skills, and automation
+- [Configuration](configuration/) — manage credentials, declare project
+  environments, turn on GPU passthrough, and configure an upstream proxy
 - [Integrations](integrations/) — connect editors and apps like VS Code and
   Cursor to a sandbox over SSH
 - [MCP gateway](mcp-gateway.md) — register MCP servers and connect them to
   sandboxed agents
 - [Customize](customize/) — reusable templates and declarative kits for
   extending or tailoring sandboxes
-- [GPU passthrough](gpu-passthrough.md) — build the NVIDIA driver bundle and
-  run GPU-accelerated workloads in a sandbox
 - [Architecture](architecture.md) — microVM isolation, workspace mounting,
   networking
-- [Upstream proxy](upstream-proxy.md) — route sandbox and daemon traffic through
-  a corporate proxy, PAC file, or your OS system proxy
 - [Security](security/) — isolation model, credential handling, and
   network policies
 - [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options

@@ -12,11 +12,11 @@ Docker Sandboxes runs the following agents out of the box:
 - [Codex](codex/)
 - [Copilot](copilot/)
 - [Cursor](cursor/)
+- [Docker Agent](docker-agent/)
 - [Droid](droid/)
 - [Gemini](gemini/)
 - [Kiro](kiro/)
 - [OpenCode](opencode/)
-- [Docker Agent](docker-agent/)
 - [Shell](shell/) — agent-less sandbox for manual setup or testing
 
 Want to pre-install tools or customize an agent's environment?

@@ -32,7 +32,7 @@ prompt from a file with `-- "$(cat prompt.txt)"`.
 Claude Code requires either an Anthropic API key or a Claude subscription.
 
 **API key**: Store your key using
-[stored secrets](../security/credentials.md#stored-secrets):
+[stored secrets](../configuration/credentials.md#stored-secrets):
 
 ```console
 $ sbx secret set anthropic
@@ -84,7 +84,7 @@ for available options.
 
 Claude Code's [agents view](https://code.claude.com/docs/en/agent-view)
 starts background sessions that run tasks in parallel. Pair it with
-[clone mode](../workflows.md#clone-mode) to keep their changes inside the
+[clone mode](../workflows/git.md#clone-mode) to keep their changes inside the
 sandbox:
 
 ```console
@@ -115,7 +115,7 @@ $ git fetch sandbox-<sandbox-name>
 $ git diff main..sandbox-<sandbox-name>/<branch>
 ```
 
-See [Git workflows](../workflows.md#git-workflows) for clone-mode details.
+See [Git workflows](../workflows/git.md) for clone-mode details.
 
 ## Base image
 

@@ -46,13 +46,13 @@ in your OS keychain. The OAuth flow runs on the host, not inside the sandbox,
 so browser-based authentication works without any extra setup.
 
 **API key**: Store your OpenAI API key using
-[stored secrets](../security/credentials.md#stored-secrets):
+[stored secrets](../configuration/credentials.md#stored-secrets):
 
 ```console
 $ sbx secret set openai
 ```
 
-See [Credentials](../security/credentials.md) for more details.
+See [Credentials](../configuration/credentials.md) for more details.
 
 ## Configuration
 

@@ -30,7 +30,7 @@ $ sbx run copilot
 ## Authentication
 
 Copilot requires a GitHub token with Copilot access. Store your token using
-[stored secrets](../security/credentials.md#stored-secrets):
+[stored secrets](../configuration/credentials.md#stored-secrets):
 
 ```console
 $ sbx secret set github --command 'gh auth token'

@@ -1,6 +1,6 @@
 ---
 title: Cursor
-weight: 33
+weight: 40
 description: |
   Use Cursor in Docker Sandboxes with API key or proxy-managed OAuth
   authentication.
@@ -32,7 +32,7 @@ $ sbx run cursor
 Cursor supports two authentication methods: an API key or OAuth.
 
 **API key**: Store your Cursor API key using
-[stored secrets](../security/credentials.md#stored-secrets):
+[stored secrets](../configuration/credentials.md#stored-secrets):
 
 ```console
 $ sbx secret set cursor

@@ -1,6 +1,6 @@
 ---
 title: Docker Agent
-weight: 70
+weight: 50
 description: |
   Use Docker Agent in Docker Sandboxes with multi-provider authentication
   supporting OpenAI, Anthropic, and more.
@@ -23,7 +23,7 @@ The workspace parameter defaults to the current directory, so
 ## Authentication
 
 Docker Agent supports multiple providers. Store keys for the providers you want
-to use with [stored secrets](../security/credentials.md#stored-secrets):
+to use with [stored secrets](../configuration/credentials.md#stored-secrets):
 
 ```console
 $ sbx secret set openai

@@ -1,6 +1,6 @@
 ---
 title: Droid
-weight: 35
+weight: 60
 description: |
   Use Droid in Docker Sandboxes with API key or OAuth authentication.
 keywords: docker sandboxes, droid, factory, ai agent, sbx
@@ -34,7 +34,7 @@ where you supply a model provider key, Factory manages model access through
 your Factory account.
 
 **API key**: Store your Factory API key using
-[stored secrets](../security/credentials.md#stored-secrets):
+[stored secrets](../configuration/credentials.md#stored-secrets):
 
 ```console
 $ sbx secret set droid

@@ -1,6 +1,6 @@
 ---
 title: Gemini
-weight: 40
+weight: 70
 description: |
   Use Google Gemini in Docker Sandboxes with proxy-managed authentication and
   API key configuration.
@@ -32,7 +32,7 @@ $ sbx run gemini
 Gemini requires either a Google API key or a Google account with Gemini access.
 
 **API key**: Store your key using
-[stored secrets](../security/credentials.md#stored-secrets):
+[stored secrets](../configuration/credentials.md#stored-secrets):
 
 ```console
 $ sbx secret set google

@@ -1,6 +1,6 @@
 ---
 title: Kiro
-weight: 50
+weight: 80
 description: |
   Use Kiro in Docker Sandboxes with device flow authentication for interactive
   AI-assisted development.

@@ -1,6 +1,6 @@
 ---
 title: OpenCode
-weight: 60
+weight: 90
 description: |
   Use OpenCode in Docker Sandboxes with multi-provider authentication and TUI
   interface for AI development.
@@ -33,7 +33,7 @@ preferred LLM provider and interact with the agent.
 ## Authentication
 
 OpenCode supports multiple providers. Store keys for the providers you want to
-use with [stored secrets](../security/credentials.md#stored-secrets):
+use with [stored secrets](../configuration/credentials.md#stored-secrets):
 
 ```console
 $ sbx secret set openai
@@ -52,7 +52,7 @@ available credentials and offers those providers in the TUI.
 
 OpenCode Zen API keys aren't part of the built-in OpenCode credentials that
 `sbx secret set` supports. To use an OpenCode Zen API key, store it as a
-[custom secret](../security/credentials.md#custom-secrets):
+[custom secret](../configuration/credentials.md#custom-secrets):
 
 Set the `OPENCODE_API_KEY` environment variable on the host, then store it:
 

@@ -1,6 +1,6 @@
 ---
 title: Shell
-weight: 90
+weight: 100
 description: Run an agent-less sandbox with a Bash login shell for manual setup, testing custom agent implementations, or inspecting a running environment.
 keywords: sandboxes, sbx, shell, agent, manual setup, testing
 ---
@@ -33,7 +33,7 @@ $ sbx run shell -- -c "echo hi"   # runs bash -l -c "echo hi"
 
 When the first argument is a bare word, it replaces `-l` instead.
 
-Store credentials using [stored secrets](../security/credentials.md#stored-secrets)
+Store credentials using [stored secrets](../configuration/credentials.md#stored-secrets)
 before running the sandbox. The proxy injects them into outbound API requests;
 credentials are never stored inside the VM:
 

@@ -1,6 +1,6 @@
 ---
 title: Architecture
-weight: 70
+weight: 100
 description: Technical architecture of Docker Sandboxes; workspace mounting, storage, networking, and sandbox lifecycle.
 keywords: docker sandboxes, architecture, microVM, workspace mounting, sandbox lifecycle
 ---
@@ -33,7 +33,7 @@ agent state and history, and workspace changes.
 
 Each sandbox maintains its own Docker daemon state, image cache, and package
 installations. Multiple sandboxes don't share images or layers. The
-[shared agent skills store](workflows.md#share-agent-skills) is an exception:
+[shared agent skills store](workflows/agent-skills.md) is an exception:
 supported agents mount the same host-side store read-write unless you opt out
 when creating the sandbox.
 
@@ -56,7 +56,7 @@ All outbound TCP traffic from the sandbox routes through a proxy on your host.
 Agents use a forward proxy for HTTP and HTTPS; other TCP traffic is forwarded
 transparently. Both paths enforce
 [network access policies](governance/access-controls/network.md). The forward
-proxy also handles [credential injection](security/credentials.md). See
+proxy also handles [credential injection](configuration/credentials.md). See
 [Network isolation](security/isolation.md#network-isolation) for how this
 works and [Default security posture](security/defaults.md) for what is
 allowed out of the box.
@@ -74,7 +74,7 @@ By default, both sandbox traffic and the daemon's own traffic follow your OS
 system proxy, so this usually works without any configuration. To set a proxy
 explicitly — with a proxy URL, a PAC file, a SOCKS5 proxy, or separate settings
 for sandbox and daemon traffic — see
-[Configure an upstream proxy](upstream-proxy.md). Upstream proxy support is
+[Configure an upstream proxy](configuration/upstream-proxy.md). Upstream proxy support is
 experimental and subject to change.
 
 Only HTTP and HTTPS traffic can be forwarded to an upstream proxy. Other TCP

@@ -0,0 +1,21 @@
+---
+title: Configure Docker Sandboxes
+linkTitle: Configuration
+weight: 60
+description: Configure credentials, project environments, GPU passthrough, and upstream proxy settings for Docker Sandboxes.
+keywords: docker sandboxes, sbx, configuration, credentials, environment files, gpu passthrough, upstream proxy
+---
+
+Configure credentials and how Docker Sandboxes run for a project, host, or
+network environment. These settings control sandbox creation, authentication,
+and connectivity. To change the tools and agent configuration inside a
+sandbox, see [Customize](../customize/).
+
+- [Credentials](credentials.md) configures API keys, authentication
+  credentials, and registry access for sandboxed agents.
+- [Environment files](environment-files.md) declare reusable project
+  configuration in `.sbxenv.yaml`.
+- [GPU passthrough](gpu-passthrough.md) configures a Linux host and sandbox for
+  NVIDIA GPU workloads.
+- [Upstream proxy](upstream-proxy.md) routes sandbox and daemon traffic through
+  an operating system or corporate proxy.
@@ -1,16 +1,19 @@
 ---
-title: Credentials
-weight: 20
+title: Manage credentials
+linkTitle: Credentials
+weight: 10
 description: How Docker Sandboxes handle API keys and authentication credentials for sandboxed agents.
 keywords: docker sandboxes, credentials, api keys, authentication, proxy, ssh agent, secrets
+aliases:
+  - /ai/sandboxes/security/credentials/
 ---
 
 Most agents need an API key for their model provider. An HTTP/HTTPS proxy on
 your host intercepts outbound requests from the sandbox, looks up the matching
 credential on the host, and overwrites the auth header before forwarding. The
 real credential stays on the host when proxy management is active; the sandbox
 sees only a sentinel value. See
-[Trust boundaries](_index.md#trust-boundaries) for how credential isolation
+[Trust boundaries](../security/_index.md#trust-boundaries) for how credential isolation
 fits into the broader sandbox security model.
 
 ## How credential injection works
@@ -182,7 +185,7 @@ $ sbx secret import openai --force
 
 Pass `--dry-run` to preview what would be imported without writing anything.
 Run `sbx secret ls` afterwards to confirm what's stored. For setting up
-credentials in CI, see [CI and headless use](../workflows.md#ci-and-headless-use).
+credentials in CI, see [CI and headless use](../workflows/automation.md).
 
 ### Built-in services
 
@@ -281,7 +284,7 @@ Use SSH agent forwarding for Git operations over SSH and SSH-based commit
 signing. The signing key must be loaded in the host SSH agent for sandboxed
 commit signing to work. Outbound SSH connections are still subject to sandbox
 network policy. For details, see
-[Commit signing](../workflows.md#commit-signing).
+[Commit signing](../workflows/git.md#commit-signing).
 
 ## Custom secrets
 
@@ -539,8 +542,8 @@ $ sbx secret rm --sandbox my-sandbox --registry ghcr.io -f
   appears when the agent starts. See the individual [agent pages](../agents/)
   for each agent's flow.
 - If you store credentials in 1Password or AWS Secrets Manager, see
-  [Sourcing credentials from 1Password](../workflows.md#sourcing-credentials-from-1password)
-  and [Sourcing credentials from AWS Secrets Manager](../workflows.md#sourcing-credentials-from-aws-secrets-manager).
+  [Sourcing credentials from 1Password](../workflows/authentication.md#source-credentials-from-1password)
+  and [Sourcing credentials from AWS Secrets Manager](../workflows/authentication.md#source-credentials-from-aws-secrets-manager).
 
 ## Custom templates and placeholder values
 

@@ -1,7 +1,7 @@
 ---
 title: Sandbox environment files
 linkTitle: Environment files
-weight: 35
+weight: 20
 description: Use a declarative .sbxenv.yaml file to describe and share your sandbox configuration.
 keywords:
   - docker sandboxes
@@ -10,6 +10,8 @@ keywords:
   - environment file
   - sandbox configuration
   - declarative
+aliases:
+  - /ai/sandboxes/sandbox-environments/
 params:
   sidebar:
     badge:
@@ -237,10 +239,10 @@ The loader rejects unknown fields and unsupported schema versions.
 `kits` accepts local directories, ZIP archives, OCI registry references, and
 Git URLs prefixed with `git+https://` or `git+ssh://`. Kits can install tools,
 configure the sandbox, and give the agent project-specific instructions. See
-[Kits](customize/kits.md) for details.
+[Kits](../customize/kits.md) for details.
 
 Remote kit sources must match the
-[kit source allowlist](customize/kits.md#restrict-kit-sources). Docker Hub is
+[kit source allowlist](../customize/kits.md#restrict-kit-sources). Docker Hub is
 allowed by default. To use Git kits from `docker/sbx-kits-contrib`, add its
 source:
 
@@ -258,11 +260,11 @@ When specified as a string, `workspace` is the path. Use the object form for
 clone mode:
 
 > [!WARNING]
-> With [direct mount](security/isolation.md#direct-mount-default), the agent can
+> With [direct mount](../security/isolation.md#direct-mount-default), the agent can
 > modify every file in a workspace. If an environment file is inside a mounted
 > workspace, the agent can change the file that controls later `sbx env`
 > commands. Store environment files outside all direct-mounted workspaces.
-> [Clone mode](security/isolation.md#clone-mode) protects files in the primary
+> [Clone mode](../security/isolation.md#clone-mode) protects files in the primary
 > repository, but additional workspaces remain direct-mounted.
 
 | Field   | Type    | Default                | Description                                                             |
@@ -363,7 +365,7 @@ registries:
 ### `mcp`
 
 The `mcp.servers` list registers servers with the built-in
-[MCP gateway](mcp-gateway.md) and adds them to the sandbox. MCP registrations
+[MCP gateway](../mcp-gateway.md) and adds them to the sandbox. MCP registrations
 are host-global and remain after `sbx env rm`.
 
 | Field     | Type            | Required | Default | Description                                                     |

@@ -3,7 +3,9 @@ title: Enable NVIDIA GPU passthrough
 linkTitle: GPU passthrough
 description: Run GPU-accelerated workloads in a sandbox by building and installing the NVIDIA driver bundle for VFIO passthrough.
 keywords: docker sandboxes, sbx, gpu, gpu passthrough, nvidia, vfio, iommu, driver bundle, cuda
-weight: 65
+weight: 30
+aliases:
+  - /ai/sandboxes/gpu-passthrough/
 ---
 
 > [!IMPORTANT]