From f27a8277c3ddcaa6cecd0049d415fae11fb4fc80 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 28 Oct 2026 07:39:49 +0000 Subject: [PATCH 1/2] docs: explain adoption of an existing environment sandbox Lost environment records can prevent attachment to a matching sandbox. Document interactive adoption, its approval limits, and later removal. --- .../configuration/environment-files.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index 5a5b32fefe5..7eb51a8afb7 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -503,6 +503,23 @@ approve the plan. They remain disabled even if you cancel the plan or restart the daemon. To enable them again, run `sbx env run` without the flag and approve the plan. Credential `command` sources still run when their secrets are needed. +## Recover an existing local sandbox + +If an upgrade or state reset loses the environment's records, `sbx env run` +can refuse to attach to an existing sandbox with the environment's name. +Run `sbx env run` at an interactive terminal. If the sandbox matches everything +the environment declares but has no ownership records or environment-file bind +showing that `sbx env` created it, the command asks whether to adopt it. + +Confirm only if you want the environment to manage that sandbox. After adoption +and plan approval, later runs recognize the same sandbox, and `sbx env rm` +can remove it. A replacement sandbox needs its own confirmation. + +`--force` approves the plan, not adoption. Non-interactive runs still refuse a +sandbox that needs adoption. A sandbox that conflicts with the environment's +declarations isn't offered adoption. `sbx env create` doesn't offer adoption +either: use `sbx env run` for this recovery. + ## Update an environment For an existing sandbox, `sbx env run` applies updated `env` values to the new From 7a50c7ca1fe0477e1fd34db79abfa7e198547641 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 28 Oct 2026 14:38:50 +0000 Subject: [PATCH 2/2] docs: clarify recovery after losing environment state The sandbox adoption guidance did not explain the failure users encounter or why recovery is useful. Lead with the refusal message and explain how to preserve the existing sandbox and recover an automated run. --- .../configuration/environment-files.md | 34 ++++++++++--------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index 7eb51a8afb7..8257fb7a146 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -503,22 +503,24 @@ approve the plan. They remain disabled even if you cancel the plan or restart the daemon. To enable them again, run `sbx env run` without the flag and approve the plan. Credential `command` sources still run when their secrets are needed. -## Recover an existing local sandbox - -If an upgrade or state reset loses the environment's records, `sbx env run` -can refuse to attach to an existing sandbox with the environment's name. -Run `sbx env run` at an interactive terminal. If the sandbox matches everything -the environment declares but has no ownership records or environment-file bind -showing that `sbx env` created it, the command asks whether to adopt it. - -Confirm only if you want the environment to manage that sandbox. After adoption -and plan approval, later runs recognize the same sandbox, and `sbx env rm` -can remove it. A replacement sandbox needs its own confirmation. - -`--force` approves the plan, not adoption. Non-interactive runs still refuse a -sandbox that needs adoption. A sandbox that conflicts with the environment's -declarations isn't offered adoption. `sbx env create` doesn't offer adoption -either: use `sbx env run` for this recovery. +## Recover after losing environment state + +If `sbx env run` reports that a local sandbox "agrees with everything this +environment declares" but "nothing was done", the sandbox still exists, but +`sbx` cannot verify that it belongs to this environment. This can happen after +an upgrade or state reset loses the environment's records. + +To keep using that sandbox without deleting and recreating it, run +`sbx env run` in an interactive terminal with the same environment file paths +and sandbox name. The command asks whether to adopt the sandbox. Confirm only +if this is the sandbox you want the environment to manage, then review and +approve the environment plan. Later runs recognize that sandbox, and +`sbx env rm` can remove it. + +For an automated run that fails with this error, complete this recovery +interactively before retrying the automation. `--force` approves the plan but +doesn't confirm adoption. Only `sbx env run` offers adoption, and only when the +sandbox matches the environment's declarations. ## Update an environment