Skip to content

Document recovery of an existing environment sandbox #26469

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dvdksn wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document recovery of an existing environment sandbox #26469

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f27a827
docs: explain adoption of an existing environment sandbox
dvdksn Oct 28, 2026
7a50c7c
docs: clarify recovery after losing environment state
dvdksn Oct 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions content/manuals/ai/sandboxes/configuration/environment-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -503,6 +503,25 @@ 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 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

For an existing sandbox, `sbx env run` applies updated `env` values to the new
Expand Down