Document recovery of an existing environment sandbox (#26469)

Explain how to adopt a matching local sandbox when lost environment
records prevent attachment. Clarify that adoption requires interactive
confirmation, is separate from plan approval, and makes the sandbox
eligible for removal with `sbx env rm`.

Validation: scoped Markdown and Vale checks pass. Runtime recovery was
not exercised because `sbx` is unavailable. Release availability remains
unconfirmed.
This commit is contained in:
David Karlsson authored and GitHub committed 2026-11-04 10:04:52 +01:00
1 parent 8da69ed6c2
commit 1847e193be
1 file changed
+19
@@ -569,6 +569,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