Deprecations
agents-sandbox is pre-1.0 but holds a high UX bar: a renamed flag, config key, environment variable, or command keeps working with a one-time warning before it is removed.
How a deprecation behaves:
- A renamed flag, config key, or environment variable still works with lower precedence than its replacement and prints a one-time warning to stderr.
- The replacement always wins: a deprecated form resolves only when its replacement is unset. Setting both is not an error.
- A deprecated project-Dockerfile spelling has no replacement to resolve against, so it warns on every ensure that uses the Dockerfile (see Project Dockerfiles).
- Deprecated forms are hidden from
--helpbut still honored. - A deprecated form survives at least one minor release after the release that introduces it, and its removal is announced in the release notes. A removal only lands in a minor release, never a patch.
This list is the current register. It is also recorded in the Deprecated section of the
changelog.
| Deprecated form | Replacement | Eligible removal |
|---|---|---|
--dind flag, dind config key, AGENTS_SANDBOX_DIND |
--docker, docker, AGENTS_SANDBOX_DOCKER |
0.8.0 |
agents-sandbox/runner-base-dind base image |
agents-sandbox/runner-base-docker |
0.8.0 |
# agents-sandbox:dind Dockerfile marker |
# agents-sandbox:docker |
0.8.0 |
OPENCODE_SANDBOX_* environment variables |
AGENTS_SANDBOX_* |
0.8.0 |
sandbox list --names |
global -q / --quiet |
0.8.0 |
prune --age (and -a) |
--older-than |
0.8.0 |
volume migrate / reset / edit --rebuild |
run agents-sandbox build first |
0.8.0 |
--opencode-version |
--agent-version |
0.7.0 |
The removal column is an eligibility floor, not a promise: a removed form only disappears in a minor release, never a patch.
Retiring a form
A rename is shimmed: the old flag, config key, environment variable, or subcommand stays as an alias of the new one for at least one minor release. A rename is never a silent break.
A clean break is only acceptable for a change of default behaviour, where no alias can carry the old meaning. Such
a change is documented as breaking in the changelog and release notes rather than shimmed — for example, the prune
commands began confirming by default in 0.6.0, with --yes as the escape.
A user-facing flag, config key, environment variable, or command is never removed outright: it is deprecated first. A change that drops one without a deprecation cycle is not accepted.
Project Dockerfiles
A project Dockerfile can still reference the managed docker base or place the injection marker with the legacy dind
spelling. agents-sandbox accepts both and warns whenever the project Dockerfile is used to ensure the runner image
(including when the cached image is reused). Prefer the docker spelling:
FROM agents-sandbox/runner-base-docker
# agents-sandbox:docker
See Runner Image for the base references and the marker.