From 453d86a1dfff50c23b4e47e267a9c2c40c815ec4 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 5 May 2026 09:32:32 +0200 Subject: [PATCH] sandboxes/kits: require startup commands to be idempotent Startup commands replay on every sandbox start and, with the upcoming container-restart replay support in docker/sandboxes#2541, on every container restart too. The framework can't enforce idempotency, so kit authors carry that contract themselves. Call it out in the introduction to startup commands and add a paragraph in the startup spec reference with practical guidance (existence checks, upserts, convergence). Co-Authored-By: Claude Opus 4.7 (1M context) --- content/manuals/ai/sandboxes/customize/kits.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md index 476ee8366ef..3826a60b281 100644 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ b/content/manuals/ai/sandboxes/customize/kits.md @@ -53,7 +53,8 @@ commands: ``` Startup commands cover things like launching background services, -warming caches, or refreshing config on each start: +warming caches, or refreshing config on each start. They must be +idempotent — see the [`startup`](#startup) spec reference: ```yaml commands: @@ -489,6 +490,13 @@ for non-interactive prep — launching daemons, warming caches, refreshing config — and use `commands.initFiles` for any value that needs to land on disk before the agent runs. +Startup commands must be idempotent. They run on every sandbox start +and replay on container restarts, so a command that fails or +misbehaves on a second invocation breaks the restart path. Guard +work with existence checks, use upserts instead of inserts, and +prefer commands that converge to the same end state regardless of +how many times they run. + #### `initFiles` Files written at sandbox start, with runtime substitution.