A Linux tool for creating lightweight containerized views, similar to sandboxes, to better control what agents have access to, and to allow them to make either immediate or copy-on-write changes to specified locations.
The devlayer tool creates lightweight containerized copy-on-write views of your
computer with optional network access. Its primary purpose is to run
semi-trusted programs—such as AI agents, app images, or shell installers—in an
environment that mirrors your host computer, while preventing them from
modifying your system in undesired ways, but still letting them make changes in working
directories. It can also be useful during development and testing for
doing things like testing migrations or file reorganizations as it lets you run
your code, examine the changes, reject the changes and try again rapidly.
If you’re satisfied with the outcome of your semi-trusted program, you can use the
devlayer tool to selectively accept some or all of the changes made to your
files. If you’re not satisfied, you can simply reject the changes.
Changes made within layers are easily browsable and persist until you remove them, allowing you to reuse the same layer for as long as needed and by as many processes as desired. Layers are also very lightweight and quick to create, making it practical to create new layers for each task you need to perform.
Please note: The use of the term semi-trusted is meant to distinguish code
that may do things you don’t want it to do, but isn’t actively malicious in a
sophisticated way. For real security needs, always use at least a virtual
machine if not a physically separate computer for your needs.
To build and install from source simply run make install.
For most other Linux distributions there are applicable binary packages available from the releases page: https://github.com/anoek/devlayer/releases
Binaries are provided for x86_64 and arm64, but it should compile and work on any architecture linux and rust supports.
Note that this is a Linux tool and will not work on any other operating systems.
Hop into a shell inside a new layer. The current directory is live, the rest of your system is layered.
devlayerHop back into the last layer you started in this directory
devlayer --lastTry that trendy web based install script in a layer first
curl -s https://trustmebro.sh | devlayer shLet AIs run wild in YOLO mode without too much risk
devlayer aiderCheck what files were modified outside the current directory
devlayer statusAccept changes to your shell config, copying them from the layer to the host system
devlayer accept ~/.bashrcAccept every change in the layer
devlayer accept /Stop all running processes in the layer and unmount the copy on write filesystem overlays.
devlayer stopconfig [NAME]-
Read and display the configuration. Use in conjunction with
-vto debug where configuration values are set. list [PATTERNS]-
List running layers matching these patterns (defaults to all)
status [PATTERNS]-
Show the changes in the layer. With no patterns this shows every change in the layer; patterns are relative to your current directory, for example
status .shows only changes under the current directory. diff [PATTERNS]-
Show the content of the changes in the layer. Like
status, with no patterns this covers every change in the layer. reject PATTERNS-
Reject the changes in the layer that match the patterns. At least one pattern is required; use
devlayer reject /to reject every change in the layer. Relative patterns are relative to your current directory. accept PATTERNS-
Accept the changes in the layer that match the patterns, copying them to your host. At least one pattern is required; use
devlayer accept /to accept every change in the layer. Relative patterns are relative to your current directory. sync-
Synchronize changes that might have occurred in your host file system so that they are reflected in running layers. Note, this performs a system wide filesystem sync and flushes all caches.
stop [--all]-
Kill all processes in the layer and unmount the filesystems. Note this will not reject any changes. A layer also stops by itself once nothing is running in it any more;
stopis for stopping it right away, along with anything still running in it. delete [PATTERNS]-
Stop and delete all files associated with the layers matching the provided patterns. If no patterns are provided, deletes the default or --join’ed layer.
clean-
Delete stopped ephemeral layers (created with
--new) that are more than a week old, and all layers left behind by the test suite. help-
Print this message or the help of the given subcommand(s)
-v, --log-level=<LOG_LEVEL>-
Set the log level to one of trace, debug, info, warn, or error.
-vis shorthand for enabling verbose (trace) logging. --join=<NAME>-
Join the named layer, creating it if it does not exist yet. Executables run within the same layer name will be run in the same container.
--new-
Create a new layer with an auto-generated timestamp name. This is the default when you run a command or a shell, so every run starts with a fresh layer. Cannot be used with --join or --last.
--last-
Use the newest layer created in the current directory, or else in the nearest parent directory that has layers. This is how you return to a layer, for example
devlayer --last bash. It is the default forstatus,diff,accept,reject, andstop/deletewithout patterns, so those act on the layer you last started in this project.configalso reports that layer when there is one. Cannot be used with --join or --new. --storage-dir=<STORAGE_DIR>-
Base storage directory for all layers. Defaults to
~/.devlayer/ --net[=host|none]-
Sets network access level. The default is
host, which shares your host network. Use--net=none(ornet="none"in a config file) to disable network access. With host networking the D-Bus and systemd sockets are also bound into the layer by default;--no-default-bindsturns them off. --no-bind-cwd-
By default the directory you start a layer in is bound read-write into the layer, so changes there go straight to your host without having to accept/reject them, while the rest of the system stays protected by the layer. Use
--no-bind-cwd(orno_bind_cwd = truein a config file, orDEVLAYER_NO_BIND_CWD=true) to keep that directory layered too.devlayerrefuses to bind/this way; run it from a project directory or pass--no-bind-cwd.A layer remembers the directory it was created in and whether it was bound. Re-entering it later, from any directory and with or without
--no-bind-cwd, keeps those original choices. Note that config files are still found by searching from your current directory, so joining a layer from a different project can load a different.devlayer.toml; if that changes its network, limits or binds,devlayerasks you to stop the layer first. --bind[=<MOUNTS>]-
Specify directories or files to bind into the layer bypassing the layer OverlayFS system. Examples:
-
--bind=../sharedbind a sibling directory into the layer as well as the current directory, which is bound by default. -
--bind=data1:/datato mount the relativedata1directory into the layer as/data. -
--bind=my/protected/dir::rowill mount the relativemy/protected/dirdirectory into the layer as read only. -
DEVLAYER_BIND="my/protected/dir::ro" devlayerworks as well. -
DEVLAYER_BIND="/dir1,/dir2" devlayer --bind=/dir3:/dir4:ro,/dir5style combined mix and match bind mounting also works.
-
--mask[=<PATHS>]-
Mask paths by mounting tmpfs (for directories) or /dev/null (for files) to prevent access to sensitive data. This is useful for hiding configuration or credential directories from processes in the layer. Examples:
-
--mask=~/.sshhides your SSH keys from processes in the layer -
--mask=/etc/passwdmasks the passwd file with /dev/null -
--mask=/.aws,/.config/gcloudmasks multiple paths -
DEVLAYER_MASK="/.ssh,/.aws" devlayerworks as well
-
--no-default-binds-
Disable default system bind mounts:
/dev/fuse, the D-Bus and systemd sockets (with host networking), and audio. This is useful when you want complete control over what gets mounted into the layer.Audio is on by default: the PipeWire and PulseAudio sockets from
$XDG_RUNTIME_DIRand the ALSA devices in/dev/sndare bound into the layer. Note that this also allows programs in the layer to record from your microphone. Use--no-default-bindsto turn audio off. --no-default-llm-binds-
Disable the default binds of well-known AI tool config and state, so that logins, history and settings of tools you run in the layer are not shared with your host. By default the following paths in your home directory are bound into the layer when they exist:
.claude,.claude.json,.codex,.pi,.gemini,.qwen,.aider,.cursor,.config/opencode,.local/share/opencode,.config/goose,.continue,.codeium,.config/github-copilot,.factory,.config/crushand.local/share/crush. This is independent of--no-default-binds. Other credentials such as SSH keys or GitHub tokens are never bound by default; add them with--bindif you want them. --cpus=<CPUS>-
Limit how many CPUs the layer can use. Fractional values such as
1.5are allowed. Negative values mean all but that many CPUs, so--cpus=-2on a 32 CPU machine lets the layer use 30. This limits the total CPU time the layer gets, it does not pin it to specific CPUs, so tools likenprocwill still report every CPU. --memory=<SIZE>-
Limit how much memory the layer can use, for example
512Mor4G. Suffixes are binary (1Kis 1024 bytes). Swap is not available to a layer with a memory limit, and when the layer runs out of memory the kernel kills its largest process.Resource limits use cgroup v2 and apply to every process in the layer. They are set when the layer starts, so you need to stop the layer to change them. Use
unlimitedto remove a limit set in a config file, for example--cpus=unlimitedorDEVLAYER_MEMORY=unlimited.A layer started inside another layer can’t set up limits of its own. Instead it warns and shares the limits of the layer it’s running in. Limits may not be available at all when
devlayeris run inside a container. --json-
Formats action output as a JSON blob. Does nothing for layered commands
--no-config-
Do not load config files. Environment variables will still be used.
--config[=<PATHS>]-
Load config files from the given path. Can be specified multiple times.
--ignored-
Show files that would normally be filtered out by ignore rules.
-h, --help-
Print help
-V, --version-
Print version
The CLI argument parser will treat anything after the [OPTIONS] as either an
action (listed above), or a command to run in the layer. Running a command
will implicitly start the layer if it isn’t running already.
A layer keeps running for as long as anything is running in it, including
processes left running in the background. About a second after the last
process in it exits, the layer stops by itself: its filesystems are unmounted,
but its changes are kept, so you can still status, diff, accept or
reject them, and running another command in the layer starts it again.
After the [OPTIONS], provided you’re not running an action, devlayer
will execute whatever command you provide, along with all subsequent arguments,
inside a layer.
If you want to run a command that happens to have the same name as an action,
you can use the -- flag to separate the command from the action arguments.
For example:
devlayer -- diff <path> <path>When invoked devlayer will look for files named .devlayer.conf and .devlayer.toml in your current directory and every ancestor directory up to you home directory (or / if invoked outside of a user’s home directory), as well as in ~/.config/devlayer/config.(conf|toml), and finally /etc/devlayer.(conf|toml), with more specific files overriding less specific ones.
These config files can set most of the CLI options:
# Name of the layer to join (like --join)
join="my-layer"
# Path to the directory where the layer will store its data
storage_dir="/path/to/devlayer/storage"
# "none" or "host"
net="none"
# "trace", "debug", "info", "warn", or "error"
log_level="info"
# Bind mounts to apply to the layer
bind=[
"/dir1",
"/dir2::ro",
"/dir3:/dir4:ro",
"/dir5:/dir6",
]
# Mask paths so they exist but are empty
mask=[
"~/.ssh",
]
# Resource limits
cpus=-2
memory="8G"You can also set most of the options with environment variables if you wish:
DEVLAYER_JOIN="my-layer"
DEVLAYER_STORAGE_DIR="/path/to/devlayer/storage"
DEVLAYER_NET="none"
DEVLAYER_LOG_LEVEL="info"
DEVLAYER_BIND="/my/dir"
DEVLAYER_CPUS="-2"
DEVLAYER_MEMORY="8G"Environment variables override config files, and CLI arguments take the highest precedence.
Bind mounts and masks from every source are combined. If two sources bind or
mask the same target, the more specific source wins. From lowest to highest
precedence the sources are: default binds, /etc, ~/.config, parent
directories, the current directory (or --config files in the order given),
environment variables, and CLI arguments. Different bind mounts or masks for
the same target within a single source are an error.
Despite our test suite achieving a high degree of code coverage, this is still a fairly new project so please expect well covered bugs, security issues, and rough edges. Please report any issues you run into to the issue tracker: https://github.com/anoek/devlayer/issues
devlayer uses OverlayFS to manage tracking of file changes and allow
applications to operate within the layered environment seeing those file
changes.
The safe and supported way to operate with OverlayFS file systems is to avoid making any changes to either to the "lower" file system ( your host filesystem), or to the "upper" file system (the changes that have been made in the layer.) In this regard, the safest way to work with a layer is to start your layer, do whatever you want to do within your layer, stop the layer, and then accept or reject your changes.
That said it is often convenient to ignore this and make changes to the
files on the host system, or to do things like accept or reject changes in
a running layer (which makes changes to the "upper" file system). In practice
this generally works as expected, the primary risk you run
is seeing stale or cached data within the layer if you choose to do this.
If you do run into visible problems, you may find running devlayer sync
will resolve your issues. If you would like to accept or reject changes from the
layer without first stopping the layer, devlayer will happily oblige the
request, but be aware that technically this is not supported by OverlayFS. These
operations implicitly perform the same actions as devlayer sync after their
work, so there is no need to call sync again after accepting or rejecting
changes from the layer.
Moving directories around in your host system may be problematic in a running layer, particularly if the layer has also moved a moved directory or made changes within a directory. Although nothing should explode, it’s easy to run into read errors and other file errors within your layer if you do this, so you should probably avoid doing such things.
In a layer, if you move or create a directory, then make a file change in said directory, then try to accept just that file, you will run into an error. Making some rather complicated moves and trying to only accept some of them may result in an accept erroring out in the middle and leaving a mess for you to clean up with moved directories moved to temporary locations.
If you’ve done a lot of complicated stuff, either be careful about what you attempt to partially accept, or just accept everything.
There’s not much protection against trying to do silly things yet, so don’t be surprised if silly things end up with silly results.