Repository navigation
Releases
0.4.0
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.
0.3.0
Changes:
- Add
--newand--lastto easily create ephemeral sandboxes - Add
--bind <src>:<target>and--bind <src>:<target>:rostyle binding of source directories to target directories within a sandbox - Add
--mask <dir>to mask out directories within a sandbox - You can now create a sandbox within a sandbox. Further recursion is probably possible by modifying the FILESYSTEM_MAX_STACK_DEPTH when building a Linux kernel.
- Add
--config <file>to specify a config file to load - Fix error while mounting file systems mounted under run, eg
/run/media/cdrom
0.2.0
Changes:
- Optimizations for processing large change sets
- Add support for .gitignore and .ignore files (show all with the
--ignoredflag) - Add the
deleteaction to delete stop and remove the files associated with sandboxes - Renamed the
discardaction torejectto pair better with ouracceptnomenclature - When
--net=hostis enabled we now bind dbus and/run/systemdwhich is necessary if you are using systemd as your DNS resolver
Install:
In addition to downloading from below or building from source, Arch Linux users can now install the sandbox-bin package from the AUR.
0.1.0
Initial Release
The sandbox binary, man page, and shell completion scripts can be installed by picking an appropriate package for your system and architecture below, or by building it from source, which is easily done on any somewhat modern Linux machine with an up to date rust installation.