From 1bdda1a87dc31197a60d7d46385e77d6a5954157 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 25 May 2026 17:13:07 +0200
Subject: [PATCH] sbx: document how to override sandbox-seeded agent settings

Sandboxes write settings files for some built-in agents (such as
/home/agent/.claude/settings.json for the claude agent) via a PostStart
hook in vm_configurator.go, which fires after kit static files and
initFiles. Document the overwrite behavior in kits.md and add a worked
commands.startup example in kit-examples.md.
---
 _vale/config/vocabularies/Docker/accept.txt   |  1 +
 .../ai/sandboxes/customize/kit-examples.md    | 27 +++++++++++++++++++
 .../manuals/ai/sandboxes/customize/kits.md    | 11 ++++++++
 3 files changed, 39 insertions(+)

diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt
index 4c2f75a8655f..5953894a9e9c 100644
--- a/_vale/config/vocabularies/Docker/accept.txt
+++ b/_vale/config/vocabularies/Docker/accept.txt
@@ -295,6 +295,7 @@ Zsh
 [Ff]iletypes?
 [GgCc]oroutine
 [Hh]ealthcheck
+[Hh]eredoc
 [Hh]ostname
 [Ii]nfosec
 [Ii]nline
diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md
index 1027ea8f4b54..6399ac3881bd 100644
--- a/content/manuals/ai/sandboxes/customize/kit-examples.md
+++ b/content/manuals/ai/sandboxes/customize/kit-examples.md
@@ -181,6 +181,33 @@ See the
 [FAQ](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for details.
 
+## Override 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
+`initFiles`, so a kit can't override those paths with either mechanism.
+Use `commands.startup` instead, which runs after the sandbox seeds its
+files:
+
+```yaml
+commands:
+  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
+```
+
+Startup commands replay on every sandbox start, so the script must be
+idempotent. The heredoc pattern overwrites cleanly each time.
+
 ## Fork an existing agent
 
 Agent kits (`kind: agent`) define a full agent from scratch. The most
diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md
index 6fbce14af93f..d8a1e1e18229 100644
--- a/content/manuals/ai/sandboxes/customize/kits.md
+++ b/content/manuals/ai/sandboxes/customize/kits.md
@@ -97,6 +97,17 @@ commands:
 
 See [`initFiles`](#initfiles) 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
+`initFiles`, 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
+[`commands.startup`](#startup) script instead. See
+[Override agent settings](kit-examples.md#override-agent-settings) for
+an example.
+
 ### Set environment variables
 
 Environment variables set by the kit are available to the agent at