docs: fix kit agent settings guidance (#25749)

## Summary

Replace the racy startup-based agent settings override with
sandbox-local, additive configuration examples. The Claude example
extends the built-in agent and loads an additional home settings file
with `--settings`; the OpenCode example uses `OPENCODE_CONFIG`. Clarify
that startup commands do not gate agent initialization.

@netlify /ai/sandboxes/customize/kit-examples/

- [Preview the kit
examples](https://deploy-preview-25749--docsdocker.netlify.app/ai/sandboxes/customize/kit-examples/)
- [Preview the kits
overview](https://deploy-preview-25749--docsdocker.netlify.app/ai/sandboxes/customize/kits/)
- [Preview the kit spec
reference](https://deploy-preview-25749--docsdocker.netlify.app/ai/sandboxes/customize/kit-reference/)

Closes docker/sbx-releases#408

Generated by Codex

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Codex <noreply@openai.com>

Author: 3 people

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

@@ -316,32 +316,97 @@ See the
 [FAQ](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for details.
 
-## Override agent settings
+## Customize agent settings
 
-Sandboxes seed settings files for some built-in agents during setup.
-For example, the sandbox writes `/home/agent/.claude/settings.json`
-for the `claude` agent. This happens after the kit's static files and
-`setup.files`, so a kit can't override those paths with either mechanism.
-Use `setup.startup` instead, which runs after the sandbox seeds its
-files:
+Some agents combine settings from several files. When the agent supports it,
+place kit settings in a separate file instead of replacing
+[sandbox-managed agent configuration](kits.md#sandbox-managed-agent-configuration).
 
-```yaml
-setup:
-  startup:
-    - command:
-        - sh
-        - -c
-        - |
-          mkdir -p /home/agent/.claude
-          cat > /home/agent/.claude/settings.json <<'JSON'
-          {"permissions": {"allow": ["Bash(echo:*)"]}}
-          JSON
-      user: "1000"
-      description: Write user-scope claude settings
+Claude Code's `--settings` option loads an additional settings file. Extend the
+built-in `claude` kit to add the option without reproducing its configuration,
+and place the additional file outside the path the sandbox manages:
+
+```text
+claude-sonnet/
+├── spec.yaml
+└── files/
+    └── home/
+        └── .config/
+            └── claude/
+                └── sonnet.json
+```
+
+```yaml {title="claude-sonnet/spec.yaml"}
+schemaVersion: "2"
+kind: sandbox
+name: claude-sonnet
+extends: claude
+
+sandbox:
+  command:
+    - --dangerously-skip-permissions
+    - --settings
+    - /home/agent/.config/claude/sonnet.json
+```
+
+```json {title="claude-sonnet/files/home/.config/claude/sonnet.json"}
+{
+  "model": "sonnet"
+}
+```
+
+Claude Code merges the additional file with the sandbox-managed user settings.
+Because the file is under `files/home/`, it stays inside the sandbox instead of
+being written into a directly mounted host workspace. Launch the sandbox with
+the child kit's name:
+
+```console
+$ sbx run claude-sonnet --kit ./claude-sonnet
+```
+
+OpenCode supports an additional config file through `OPENCODE_CONFIG`. Keep the
+kit's config separate from the sandbox-managed
+`/home/agent/.config/opencode/opencode.json`, for example at
+`/home/agent/.config/opencode/team.json`:
+
+```text
+opencode-team/
+├── spec.yaml
+└── files/
+    └── home/
+        └── .config/
+            └── opencode/
+                └── team.json
+```
+
+```yaml {title="opencode-team/spec.yaml"}
+schemaVersion: "2"
+kind: mixin
+name: opencode-team
+requires:
+  agent: opencode
+
+environment:
+  variables:
+    OPENCODE_CONFIG: /home/agent/.config/opencode/team.json
 ```
 
-Startup commands replay on every sandbox start, so the script must be
-idempotent. The heredoc pattern overwrites cleanly each time.
+```json {title="opencode-team/files/home/.config/opencode/team.json"}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "autoupdate": false
+}
+```
+
+OpenCode merges the custom file with its global and project config files. See
+the OpenCode [config precedence](https://opencode.ai/docs/config/#precedence-order)
+for the complete order.
+
+Agent settings mechanisms differ. If an agent doesn't support an additional
+config file, launch option, or environment variable for the setting, kits can't
+replace the sandbox-managed user settings before the agent launches.
+`setup.startup` doesn't gate the agent entrypoint, so don't use it for settings
+the agent must read during initialization.
 
 ## Fork an existing agent
 

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

@@ -167,7 +167,7 @@ sandbox:
 
 | Field                | Required | Description                                                                                                     |
 | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| `sandbox.image`      | Yes      | Docker image reference. A sandbox that sets `extends:` can inherit this from its parent.                        |
+| `sandbox.image`      | When `extends:` is omitted | Docker image reference.                                                                                         |
 | `sandbox.build`      | No       | Build configuration. Runtime support is pending, so a kit with `build:` must also set `image:`.                 |
 | `sandbox.entrypoint` | No       | Fixed process prefix as a string array. The first element is the agent binary.                                  |
 | `sandbox.command`    | No       | Mode-specific argument tail. Use a list shorthand for `default`, or a mapping with `default` and `interactive`. |
@@ -177,6 +177,12 @@ The effective command is `entrypoint` plus `command.default` for non-interactive
 launches, and `entrypoint` plus `command.interactive` for TTY sessions. If
 `interactive` is omitted, it falls back to `default`.
 
+For a kit that uses `extends:`, `sandbox.command` replaces the full inherited
+argument tail, including flags after the binary in the parent's
+`sandbox.entrypoint`. It doesn't append to that tail. Define every argument the
+child needs. For example, a child of `claude` that adds `--settings` must also
+include `--dangerously-skip-permissions` to preserve that behavior.
+
 The agent's container image must provide:
 
 - A non-root `agent` user at UID 1000 with passwordless sudo.
@@ -434,14 +440,16 @@ Runs at every sandbox start. String array, not interpreted by a shell.
 | ------------- | -------- | ----------------------------------- |
 | `command`     | —        | Command and args as a string array. |
 | `user`        | `"1000"` | User to run as. `"1000"` = agent.   |
-| `background`  | `false`  | Run in background.                  |
+| `background`  | `false`  | Block later startup commands until this command finishes. Set to `true` to let later commands run without waiting. |
 | `description` | —        | Human-readable description.         |
 
 Startup commands are non-interactive. They run before the agent
 attaches, with no terminal connected, so they can't prompt the user
 (for example, an interactive `aws login` will hang or fail). They also
 don't gate the agent's entrypoint: the agent launches once startup
-commands have been dispatched, regardless of `background`. Use them
+commands have been dispatched, regardless of `background`. A value of
+`false` waits within the startup dispatcher before it runs the next command;
+it doesn't delay the agent entrypoint. Use startup commands
 for non-interactive prep — launching daemons, warming caches,
 refreshing config — and use `setup.files` for any value that
 needs to land on disk before the agent runs.

content/manuals/ai/sandboxes/customize/kits.md

@@ -99,16 +99,30 @@ setup:
 See [`setup.files`](kit-reference.md#files) in the spec reference for all
 fields.
 
-Sandboxes seed settings files for some built-in agents during setup.
-For example, the sandbox writes `/home/agent/.claude/settings.json`
-for the `claude` agent. This happens after the kit's static files and
-`setup.files`, so kit-injected files at those paths get overwritten.
-Workspace files (such as `<workspace>/.claude/settings.local.json`)
-aren't affected, and you can ship them under `files/workspace/` as
-usual. To override a path the sandbox writes to, use a
-[`setup.startup`](kit-reference.md#startup) script instead. See
-[Override agent settings](kit-examples.md#override-agent-settings) for
-an example.
+#### Sandbox-managed agent configuration
+
+Built-in agent kits reserve the following paths for sandbox setup. Treat these
+paths as sandbox-managed, even if a file is only needed for a particular
+feature. Don't target them with static files, `setup.files`, or install
+commands. Later setup can replace your content or depend on settings that your
+file removes. In this table, `~` is `/home/agent`.
+
+| Built-in agent kit | Managed configuration paths |
+| ------------------ | --------------------------- |
+| `claude` | `~/.claude.json`, `~/.claude/settings.json`, `~/.claude/.config.json` |
+| `codex` | `~/.codex/config.toml` |
+| `copilot` | `~/.copilot/config.json` |
+| `cursor` | `~/.cursor/cli-config.json` |
+| `gemini` | `~/.gemini/settings.json` |
+| `kiro` | `~/.kiro/settings/mcp.json` |
+| `opencode` | `~/.config/opencode/opencode.json` |
+
+Use a separate settings layer when the agent supports one. For example, Claude
+Code can load an additional settings file with `--settings`, and OpenCode can
+load one from the path in `OPENCODE_CONFIG`. See
+[Customize agent settings](kit-examples.md#customize-agent-settings) for
+examples. Don't use `setup.startup` for settings the agent must read during
+initialization because startup commands don't gate the agent entrypoint.
 
 ### Set environment variables