Skip to content
anoekPublic

About

Create mixed copy-on-write, read-only, and direct access environments for LLM agents to work in

Resources

Contributing

Stars

22 stars

Watchers

1 watching

Forks

Repository files navigation

devlayer

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.

Description

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.

Installation

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.

Synopsis

devlayer [OPTIONS] <COMMAND …​>

devlayer [OPTIONS] [ACTION] [ACTION_ARGUMENTS…​]

Quick examples:

Hop into a shell inside a new layer. The current directory is live, the rest of your system is layered.

 devlayer

Hop back into the last layer you started in this directory

 devlayer --last

Try that trendy web based install script in a layer first

 curl -s https://trustmebro.sh | devlayer sh

Let AIs run wild in YOLO mode without too much risk

 devlayer aider

Check what files were modified outside the current directory

 devlayer status

Accept changes to your shell config, copying them from the layer to the host system

 devlayer accept ~/.bashrc

Accept every change in the layer

 devlayer accept /

Stop all running processes in the layer and unmount the copy on write filesystem overlays.

 devlayer stop

Actions:

config [NAME]

Read and display the configuration. Use in conjunction with -v to 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; stop is 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)

Options:

-v, --log-level=<LOG_LEVEL>

Set the log level to one of trace, debug, info, warn, or error. -v is 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 for status, diff, accept, reject, and stop/delete without patterns, so those act on the layer you last started in this project. config also 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 (or net="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-binds turns 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 (or no_bind_cwd = true in a config file, or DEVLAYER_NO_BIND_CWD=true) to keep that directory layered too. devlayer refuses 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, devlayer asks you to stop the layer first.

--bind[=<MOUNTS>]

Specify directories or files to bind into the layer bypassing the layer OverlayFS system. Examples:

  • --bind=../shared bind a sibling directory into the layer as well as the current directory, which is bound by default.

  • --bind=data1:/data to mount the relative data1 directory into the layer as /data.

  • --bind=my/protected/dir::ro will mount the relative my/protected/dir directory into the layer as read only.

  • DEVLAYER_BIND="my/protected/dir::ro" devlayer works as well.

  • DEVLAYER_BIND="/dir1,/dir2" devlayer --bind=/dir3:/dir4:ro,/dir5 style 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=~/.ssh hides your SSH keys from processes in the layer

  • --mask=/etc/passwd masks the passwd file with /dev/null

  • --mask=/.aws,/.config/gcloud masks multiple paths

  • DEVLAYER_MASK="/.ssh,/.aws" devlayer works 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_DIR and the ALSA devices in /dev/snd are bound into the layer. Note that this also allows programs in the layer to record from your microphone. Use --no-default-binds to 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/crush and .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 --bind if you want them.

--cpus=<CPUS>

Limit how many CPUs the layer can use. Fractional values such as 1.5 are allowed. Negative values mean all but that many CPUs, so --cpus=-2 on 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 like nproc will still report every CPU.

--memory=<SIZE>

Limit how much memory the layer can use, for example 512M or 4G. Suffixes are binary (1K is 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 unlimited to remove a limit set in a config file, for example --cpus=unlimited or DEVLAYER_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 devlayer is 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

Commands

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>

Config Files

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"

Environment Variables

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.

Caveats & Limitations

Maturity

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

Changing files in both the host system and the layer

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 out from under a 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.

Partial accepts that depend on other non-accepted 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.

About

Create mixed copy-on-write, read-only, and direct access environments for LLM agents to work in

Resources

Contributing

Stars

22 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages