From 08031dff3322a7c1f070490300ba790b0743c739 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 4 Nov 2026 10:04:12 +0000 Subject: [PATCH 1/3] docs: preserve sandbox conversations with session mixins Removing a sandbox can discard Claude Code and Codex conversations. Document versioned session mixins, how to resume saved conversations, and their separation from agents running directly on the host. --- .../ai/sandboxes/agents/claude-code.md | 7 ++++ content/manuals/ai/sandboxes/agents/codex.md | 7 ++++ .../ai/sandboxes/customize/use-kits.md | 35 +++++++++++++++++++ 3 files changed, 49 insertions(+) diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index 931a5d7f8429..93edaa9a11cf 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -33,6 +33,13 @@ prompt from a file with `-- "$(cat prompt.txt)"`. To create a [mountless sandbox](../usage.md#choose-a-workspace), use `sbx create` without a workspace path, then attach by name. +## Preserve conversations after sandbox removal + +To keep Claude Code conversations when you remove and recreate a local sandbox, +use a v3 workload with its session mixin. See +[Preserve Claude Code and Codex conversations](../customize/use-kits.md#preserve-claude-code-and-codex-conversations) +for commands and steps to resume a conversation. + ## Authentication For the default Anthropic models, Claude Code requires either an Anthropic diff --git a/content/manuals/ai/sandboxes/agents/codex.md b/content/manuals/ai/sandboxes/agents/codex.md index da3e8d289a9e..e336f70cc6e1 100644 --- a/content/manuals/ai/sandboxes/agents/codex.md +++ b/content/manuals/ai/sandboxes/agents/codex.md @@ -32,6 +32,13 @@ $ sbx run codex To create a [mountless sandbox](../usage.md#choose-a-workspace), use `sbx create` without a workspace path, then attach by name. +## Preserve conversations after sandbox removal + +To keep Codex conversations when you remove and recreate a local sandbox, +use a v3 workload with its session mixin. See +[Preserve Claude Code and Codex conversations](../customize/use-kits.md#preserve-claude-code-and-codex-conversations) +for commands and steps to resume a conversation. + ## Authentication For the default OpenAI models, `sbx run codex` prompts you to authenticate on diff --git a/content/manuals/ai/sandboxes/customize/use-kits.md b/content/manuals/ai/sandboxes/customize/use-kits.md index 1879ddc09fb0..f67ab3da3950 100644 --- a/content/manuals/ai/sandboxes/customize/use-kits.md +++ b/content/manuals/ai/sandboxes/customize/use-kits.md @@ -328,6 +328,41 @@ discarded when the sandbox stops. For how to preserve storage when changing a kit, see [Configure the volume](author/patterns.md#configure-the-volume). +### Preserve Claude Code and Codex conversations + +For local sandboxes, add a session mixin to keep conversations after removing +and recreating the sandbox, including when you use `--rm`. Choose the mixin +that matches your v3 workload: + +{{< tabs >}} +{{< tab name="Claude Code" >}} + +```console +$ sbx run --rm docker.io/docker/sbx-kit-claude:2.1.267 --kit sbx/claude-sessions:1.0.0 +``` + +{{< /tab >}} +{{< tab name="Codex" >}} + +```console +$ sbx run --rm docker.io/docker/sbx-kit-codex:0.155.1 --kit sbx/codex-sessions:1.0.0 +``` + +{{< /tab >}} +{{< /tabs >}} + +Start a conversation, then enter `/exit`. Run the same command again from the +same project directory and enter `/resume` inside the agent to select the saved +conversation. + +The mixins use host directories managed by Docker Sandboxes to store session +state. They don't share conversations with Claude Code or Codex running directly +on your host. Include the session mixin each time you recreate the sandbox. + +To choose a host directory, see [Choose directories for kit host mounts](#choose-directories-for-kit-host-mounts). +The sandbox mount paths are `/home/agent/claude-history` for Claude Code and +`/home/agent/codex-history` for Codex. + ## Restrict kit sources [`kit.allowedSources`](../configuration/settings.md#kitallowedsources) controls From df479176ced0bf8d836d9852d9c050ea6a1ec695 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 4 Nov 2026 12:00:32 +0000 Subject: [PATCH 2/3] docs: use built-in agent names for session mixins Built-in Claude Code and Codex names resolve to published v3 kits in sbx v0.51.0. Use those names in conversation persistence examples and remove conflicting kit guidance. --- .../ai/sandboxes/agents/claude-code.md | 2 +- content/manuals/ai/sandboxes/agents/codex.md | 2 +- .../ai/sandboxes/customize/use-kits.md | 20 +++++++++---------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index 93edaa9a11cf..14b29879df9c 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -36,7 +36,7 @@ To create a [mountless sandbox](../usage.md#choose-a-workspace), use ## Preserve conversations after sandbox removal To keep Claude Code conversations when you remove and recreate a local sandbox, -use a v3 workload with its session mixin. See +add its session mixin when creating the sandbox. See [Preserve Claude Code and Codex conversations](../customize/use-kits.md#preserve-claude-code-and-codex-conversations) for commands and steps to resume a conversation. diff --git a/content/manuals/ai/sandboxes/agents/codex.md b/content/manuals/ai/sandboxes/agents/codex.md index e336f70cc6e1..ca97259c6bb3 100644 --- a/content/manuals/ai/sandboxes/agents/codex.md +++ b/content/manuals/ai/sandboxes/agents/codex.md @@ -35,7 +35,7 @@ To create a [mountless sandbox](../usage.md#choose-a-workspace), use ## Preserve conversations after sandbox removal To keep Codex conversations when you remove and recreate a local sandbox, -use a v3 workload with its session mixin. See +add its session mixin when creating the sandbox. See [Preserve Claude Code and Codex conversations](../customize/use-kits.md#preserve-claude-code-and-codex-conversations) for commands and steps to resume a conversation. diff --git a/content/manuals/ai/sandboxes/customize/use-kits.md b/content/manuals/ai/sandboxes/customize/use-kits.md index f67ab3da3950..33e2c22c7f46 100644 --- a/content/manuals/ai/sandboxes/customize/use-kits.md +++ b/content/manuals/ai/sandboxes/customize/use-kits.md @@ -13,8 +13,8 @@ settings. You run kits you build yourself or get from another publisher in the same way: give `sbx` a reference, and Docker Sandboxes prepares the environment and applies the kit's settings. -Docker recommends v3 kits. V2 remains supported and is the default format -for built-in agent references such as `claude` and `codex`. +Docker recommends v3 kits. With sbx v0.51.0 and later, built-in agent names +such as `claude` and `codex` resolve to published kits. ## Run a kit @@ -32,13 +32,12 @@ $ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-v3-kit ### Published v3 workloads -Use these published v3 workloads in place of built-in shortcuts when adding -v3 mixins with `sbx run` or `sbx create`. +To select a specific workload version when adding v3 mixins with `sbx run` +or `sbx create`, use a versioned reference: A workload's agent name comes from the last component of its repository name. -It must differ from built-in agent names: `docker/sbx-kit-claude` registers -`sbx-kit-claude`, while `sbx/claude` conflicts with built-in `claude` and -fails to register. Changing the sandbox's `--name` doesn't change the agent name. +For example, `docker/sbx-kit-claude` registers `sbx-kit-claude`. Changing the +sandbox's `--name` doesn't change the agent name. | Built-in agent | V3 workload OCI reference | | --- | --- | @@ -332,20 +331,21 @@ For how to preserve storage when changing a kit, see For local sandboxes, add a session mixin to keep conversations after removing and recreating the sandbox, including when you use `--rm`. Choose the mixin -that matches your v3 workload: +that matches your agent. These examples use the built-in names with sbx +v0.51.0 or later: {{< tabs >}} {{< tab name="Claude Code" >}} ```console -$ sbx run --rm docker.io/docker/sbx-kit-claude:2.1.267 --kit sbx/claude-sessions:1.0.0 +$ sbx run --rm claude --kit sbx/claude-sessions:1.0.0 ``` {{< /tab >}} {{< tab name="Codex" >}} ```console -$ sbx run --rm docker.io/docker/sbx-kit-codex:0.155.1 --kit sbx/codex-sessions:1.0.0 +$ sbx run --rm codex --kit sbx/codex-sessions:1.0.0 ``` {{< /tab >}} From ce439a783d15fb9421e13b80d4bf8f4fa0f82e04 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 4 Nov 2026 12:12:53 +0000 Subject: [PATCH 3/3] docs: keep conversation persistence changes focused The conversation persistence update also changed general v3 workload guidance. Restore that guidance and use the existing versioned workload references in the session examples. --- .../ai/sandboxes/customize/use-kits.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/content/manuals/ai/sandboxes/customize/use-kits.md b/content/manuals/ai/sandboxes/customize/use-kits.md index 33e2c22c7f46..ae9818f9bfd8 100644 --- a/content/manuals/ai/sandboxes/customize/use-kits.md +++ b/content/manuals/ai/sandboxes/customize/use-kits.md @@ -13,8 +13,8 @@ settings. You run kits you build yourself or get from another publisher in the same way: give `sbx` a reference, and Docker Sandboxes prepares the environment and applies the kit's settings. -Docker recommends v3 kits. With sbx v0.51.0 and later, built-in agent names -such as `claude` and `codex` resolve to published kits. +Docker recommends v3 kits. V2 remains supported and is the default format +for built-in agent references such as `claude` and `codex`. ## Run a kit @@ -32,12 +32,13 @@ $ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-v3-kit ### Published v3 workloads -To select a specific workload version when adding v3 mixins with `sbx run` -or `sbx create`, use a versioned reference: +Use these published v3 workloads in place of built-in shortcuts when adding +v3 mixins with `sbx run` or `sbx create`. A workload's agent name comes from the last component of its repository name. -For example, `docker/sbx-kit-claude` registers `sbx-kit-claude`. Changing the -sandbox's `--name` doesn't change the agent name. +It must differ from built-in agent names: `docker/sbx-kit-claude` registers +`sbx-kit-claude`, while `sbx/claude` conflicts with built-in `claude` and +fails to register. Changing the sandbox's `--name` doesn't change the agent name. | Built-in agent | V3 workload OCI reference | | --- | --- | @@ -331,21 +332,22 @@ For how to preserve storage when changing a kit, see For local sandboxes, add a session mixin to keep conversations after removing and recreating the sandbox, including when you use `--rm`. Choose the mixin -that matches your agent. These examples use the built-in names with sbx -v0.51.0 or later: +that matches your agent: {{< tabs >}} {{< tab name="Claude Code" >}} ```console -$ sbx run --rm claude --kit sbx/claude-sessions:1.0.0 +$ sbx run --rm docker.io/docker/sbx-kit-claude:2.1.267 \ + --kit sbx/claude-sessions:1.0.0 ``` {{< /tab >}} {{< tab name="Codex" >}} ```console -$ sbx run --rm codex --kit sbx/codex-sessions:1.0.0 +$ sbx run --rm docker.io/docker/sbx-kit-codex:0.155.1 \ + --kit sbx/codex-sessions:1.0.0 ``` {{< /tab >}}