Repository navigation
sandbox is now devlayer. This release renames the project and changes
several defaults so that each run starts in a fresh layer, keeps your project
directory live, and has network access. Please read the upgrade notes before
you upgrade.
Upgrading from sandbox 0.3.0
The rename touches every name the tool uses. devlayer does not read any of the
old names, so you must move your settings by hand.
| 0.3.0 (sandbox) | 0.4.0 (devlayer) |
|---|---|
sandbox command |
devlayer command |
~/.sandboxes/ storage directory |
~/.devlayer/ |
.sandbox.conf / .sandbox.toml |
.devlayer.conf / .devlayer.toml |
~/.config/sandbox/config.(conf|toml) |
~/.config/devlayer/config.(conf|toml) |
/etc/sandbox.(conf|toml) |
/etc/devlayer.(conf|toml) |
SANDBOX_* environment variables |
DEVLAYER_* |
--name / name= / SANDBOX_NAME |
--join / join= / DEVLAYER_JOIN |
sandbox packages |
devlayer packages |
To upgrade:
- Accept or reject the changes in your old sandboxes, then run
sandbox stop --all. - Uninstall the
sandboxpackage (orsandbox-binfrom the AUR). - Install the
devlayerpackage. - Rename your config files and environment variables as shown in the table.
- Delete
~/.sandboxes/when you no longer need it.
Changed defaults
These changes alter the behavior of commands you may already use.
- Each run creates a new layer. Running a command or a shell now acts
like--new. Before, every run used one shared layer namedsandbox. To
reuse a layer, use--join <name>or--last. --lastknows about directories. It now selects the newest layer that
was created in the current directory, or else in the nearest parent
directory that has layers.- Actions use
--lastby default.status,diff,accept,reject,
andstop/deletewithout patterns now act on the layer you last started
in this project. - The current directory is bound read-write by default. Changes in the
directory where you start a layer go straight to your host. The rest of
the system stays layered. To keep the directory layered too, use
--no-bind-cwd,no_bind_cwd = true, orDEVLAYER_NO_BIND_CWD=true.
devlayer refuses to bind/or your home directory this way. To bind
your home directory anyway, use--bind=.. - Host networking is the default. To disable network access, use
--net=noneornet="none"in a config file. statusanddiffshow the whole layer. Before, they showed only
changes under the current directory. Usestatus .to see only those
changes.acceptandrejectneed a pattern. Before, they acted on the
current directory when you gave no pattern. Useaccept /orreject /
to act on every change in the layer.- Layers stop when they are idle. About one second after the last
process in a layer exits, the layer unmounts its filesystems. It keeps
its changes, and the next command you run in it starts it again.
Orphaned processes in a layer are now reaped.
New features
- Resource limits.
--cpusand--memorylimit a layer with cgroup v2.
--cpusaccepts fractions (1.5) and negative values (-2means "all
but two CPUs").--memoryaccepts sizes such as512Mor4Gand
disables swap for the layer. You can also set them withDEVLAYER_CPUS,
DEVLAYER_MEMORY, or a config file. Useunlimitedto remove a limit
that a less specific source sets. A nested layer shares the limits of
its outer layer. - Audio. The PipeWire and PulseAudio sockets and the ALSA devices are
bound into layers by default. This also lets programs in the layer use
your microphone. To turn audio off, use--no-default-binds. - AI tool config is shared by default. The config and state of
well-known AI tools are bound into the layer when they exist, so logins
and settings carry over. This includes~/.claude,~/.codex,
~/.gemini,~/.aider,~/.cursor, opencode, goose, crush, and others.
To keep them separate, use--no-default-llm-binds. devlayer never binds
SSH keys or other credentials by default. cleanaction.devlayer cleandeletes stopped--newlayers that
are more than a week old.- More specific config overrides binds and masks. A bind or mask for a
target now replaces one for the same target from a less specific source.
Before, devlayer reported this as a conflict. You can now override the
default binds.
Fixes
- Fix entering a layer on Linux 6.18 and later, which changed the ptrace
permission checks forsetns(). - Report an error when you enter a running layer with network, limit, or
bind settings that are different from its own. Before, devlayer ignored
the new settings. - Fix duplicate bind and mask detection when the same path is given in
different forms. - Give each concurrent
--newlaunch its own layer, and keep a layer up
while a command is starting in it. - Name the mount point in the error message when devlayer cannot read a
mount.
Security hardening
- devlayer does not follow symlinks in the storage directory.
- devlayer trusts a layer's pid file only when it names the layer's own
PID 1. - A layer's PID 1 exits safely on SIGTERM.