docs(sandboxes): align credential and kit-spec docs to schemaVersion 2

Reframe the credential and kit-authoring docs to the v2 launch state:

- credentials.md: credential bindings as the authorization mechanism,
  first-run approval (API key vs OAuth), fail-closed by default for
  schemaVersion 2 kits, environment variables sourced via a binding
- kit-reference.md: default examples to schemaVersion "2"; add a
  "Schema versions" section + v1->v2 mapping; rewrite credentials
  (credentials[] / apiKey / oauth), network (caps.network), drop proxyManaged
- kits.md, kit-examples.md: convert examples to v2
- agent pages: env-var auth now flows through a credential binding
- troubleshooting.md: add the "no approved binding" failure

Held as a draft until built-in agents move to schemaVersion 2.
build-an-agent.md remains on v1 (separate follow-up).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dvdksn

content/manuals/ai/sandboxes/agents/claude-code.md

@@ -38,9 +38,10 @@ Claude Code requires either an Anthropic API key or a Claude subscription.
 $ sbx secret set -g anthropic
 ```
 
-Alternatively, export the `ANTHROPIC_API_KEY` environment variable in your
-shell before running the sandbox. See
-[Credentials](../security/credentials.md) for details on both methods.
+You can also source the key from the `ANTHROPIC_API_KEY` environment variable
+through a [credential binding](../security/credentials.md#credential-bindings);
+the sandbox prompts you to approve one on first run. See
+[Credentials](../security/credentials.md) for details.
 
 **Claude subscription**: If no API key is set, Claude Code prompts you to
 authenticate interactively using OAuth. The proxy handles the OAuth flow, so

content/manuals/ai/sandboxes/agents/codex.md

@@ -52,8 +52,9 @@ so browser-based authentication works without any extra setup.
 $ sbx secret set -g openai
 ```
 
-Alternatively, export the `OPENAI_API_KEY` environment variable in your shell
-before running the sandbox.
+You can also source the key from the `OPENAI_API_KEY` environment variable
+through a [credential binding](../security/credentials.md#credential-bindings);
+the sandbox prompts you to approve one on first run.
 
 See [Credentials](../security/credentials.md) for more details.
 

content/manuals/ai/sandboxes/agents/copilot.md

@@ -36,9 +36,11 @@ Copilot requires a GitHub token with Copilot access. Store your token using
 $ echo "$(gh auth token)" | sbx secret set -g github
 ```
 
-Alternatively, export the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in
-your shell before running the sandbox. See
-[Credentials](../security/credentials.md) for details on both methods.
+You can also source the token from the `GH_TOKEN` or `GITHUB_TOKEN` environment
+variable through a
+[credential binding](../security/credentials.md#credential-bindings); the
+sandbox prompts you to approve one on first run. See
+[Credentials](../security/credentials.md) for details.
 
 ## Configuration
 

content/manuals/ai/sandboxes/agents/cursor.md

@@ -38,9 +38,10 @@ Cursor supports two authentication methods: an API key or OAuth.
 $ sbx secret set -g cursor
 ```
 
-Alternatively, export the `CURSOR_API_KEY` environment variable in your shell
-before running the sandbox. See
-[Credentials](../security/credentials.md) for details on both methods.
+You can also source the key from the `CURSOR_API_KEY` environment variable
+through a [credential binding](../security/credentials.md#credential-bindings);
+the sandbox prompts you to approve one on first run. See
+[Credentials](../security/credentials.md) for details.
 
 **OAuth**: If no API key is set, Cursor prompts you to sign in interactively
 on first run. The proxy intercepts the token exchange with

content/manuals/ai/sandboxes/agents/docker-agent.md

@@ -38,11 +38,12 @@ $ sbx secret set -g openrouter
 You only need to configure the providers you want to use. Docker Agent detects
 available credentials and routes requests to the appropriate provider.
 
-Alternatively, export the environment variables (`OPENAI_API_KEY`,
+You can also source these from environment variables (`OPENAI_API_KEY`,
 `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `NEBIUS_API_KEY`,
-`MISTRAL_API_KEY`, `OPENROUTER_API_KEY`) in your shell before running the
-sandbox. See
-[Credentials](../security/credentials.md) for details on both methods.
+`MISTRAL_API_KEY`, `OPENROUTER_API_KEY`) through
+[credential bindings](../security/credentials.md#credential-bindings); the
+sandbox prompts you to approve one per provider on first run. See
+[Credentials](../security/credentials.md) for details.
 
 ## Configuration
 

content/manuals/ai/sandboxes/agents/droid.md

@@ -40,9 +40,10 @@ your Factory account.
 $ sbx secret set -g droid
 ```
 
-Alternatively, export the `FACTORY_API_KEY` environment variable in your shell
-before running the sandbox. See
-[Credentials](../security/credentials.md) for details on both methods.
+You can also source the key from the `FACTORY_API_KEY` environment variable
+through a [credential binding](../security/credentials.md#credential-bindings);
+the sandbox prompts you to approve one on first run. See
+[Credentials](../security/credentials.md) for details.
 
 **OAuth**: If no API key is set, Droid prompts you to authenticate
 interactively on first run. The proxy handles the OAuth flow, so credentials

content/manuals/ai/sandboxes/agents/gemini.md

@@ -38,9 +38,11 @@ Gemini requires either a Google API key or a Google account with Gemini access.
 $ sbx secret set -g google
 ```
 
-Alternatively, export the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment
-variable in your shell before running the sandbox. See
-[Credentials](../security/credentials.md) for details on both methods.
+You can also source the key from the `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+environment variable through a
+[credential binding](../security/credentials.md#credential-bindings); the
+sandbox prompts you to approve one on first run. See
+[Credentials](../security/credentials.md) for details.
 
 **Google account**: If no API key is set, Gemini prompts you to sign in
 interactively when it starts. Interactive authentication is scoped to the

content/manuals/ai/sandboxes/agents/opencode.md

@@ -48,10 +48,12 @@ $ sbx secret set -g openrouter
 You only need to configure the providers you want to use. OpenCode detects
 available credentials and offers those providers in the TUI.
 
-You can also use environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
-`GOOGLE_GENERATIVE_AI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`,
-`AWS_ACCESS_KEY_ID`, `OPENROUTER_API_KEY`). See
-[Credentials](../security/credentials.md) for details on both methods.
+You can also source these from environment variables (`OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `XAI_API_KEY`,
+`GROQ_API_KEY`, `AWS_ACCESS_KEY_ID`, `OPENROUTER_API_KEY`) through
+[credential bindings](../security/credentials.md#credential-bindings); the
+sandbox prompts you to approve one per provider on first run. See
+[Credentials](../security/credentials.md) for details.
 
 ## Configuration
 

content/manuals/ai/sandboxes/agents/shell.md

@@ -33,9 +33,11 @@ $ sbx run shell -- -c "echo hi"   # runs bash -l -c "echo hi"
 
 When the first argument is a bare word, it replaces `-l` instead.
 
-Set your API keys as environment variables so the sandbox proxy can inject
-them into API requests automatically. Credentials are never stored inside
-the VM:
+Provide your API keys as environment variables so the sandbox proxy can inject
+them into API requests. The proxy injects a key once a
+[credential binding](../security/credentials.md#credential-bindings) authorizes
+it — the sandbox prompts you to approve one on first run. Credentials are never
+stored inside the VM:
 
 ```console
 $ export ANTHROPIC_API_KEY=sk-ant-xxxxx

content/manuals/ai/sandboxes/customize/kit-examples.md

@@ -35,7 +35,7 @@ ruff-lint/
 ```
 
 ```yaml {title="ruff-lint/spec.yaml"}
-schemaVersion: "1"
+schemaVersion: "2"
 kind: mixin
 name: ruff-lint
 displayName: Ruff
@@ -95,7 +95,7 @@ the kit and install each certificate before running
 `update-ca-certificates`.
 
 ```yaml {title="internal-ca/spec.yaml"}
-schemaVersion: "1"
+schemaVersion: "2"
 kind: mixin
 name: internal-ca
 
@@ -196,7 +196,7 @@ docker-review/
 ```
 
 ```yaml {title="docker-review/spec.yaml"}
-schemaVersion: "1"
+schemaVersion: "2"
 kind: mixin
 name: docker-review
 displayName: Dockerfile review skill
@@ -260,7 +260,7 @@ built-in `claude` agent but drops `--dangerously-skip-permissions` so
 every tool call prompts for approval:
 
 ```yaml {title="claude-safe/spec.yaml"}
-schemaVersion: "1"
+schemaVersion: "2"
 kind: sandbox
 name: claude-safe
 displayName: Claude Code (with approval prompts)
@@ -272,22 +272,22 @@ sandbox:
   entrypoint:
     run: [claude]
 
-network:
-  serviceDomains:
-    api.anthropic.com: anthropic
-    console.anthropic.com: anthropic
-  serviceAuth:
-    anthropic:
-      headerName: x-api-key
-      valueFormat: "%s"
-  allowedDomains:
-    - "claude.com:443"
+caps:
+  network:
+    allow:
+      - "claude.com:443"
 
 credentials:
-  sources:
-    anthropic:
-      env:
-        - ANTHROPIC_API_KEY
+  - service: anthropic
+    apiKey:
+      name: ANTHROPIC_API_KEY
+      inject:
+        - domain: api.anthropic.com
+          header: x-api-key
+          format: "%s"
+        - domain: console.anthropic.com
+          header: x-api-key
+          format: "%s"
 ```
 
 Launch with the kit's `name:` as the agent argument to `sbx run`: