doos
Version: see VERSION (currently 0.1.3). Release history: CHANGELOG.md.
User-level containers in C++20: overlayfs over the host's /usr, /etc, /opt, user/mount/pid namespaces, networking through slirp4netns. No root at runtime.
doos list
doos get_or_create [--net slirp|host|none] NAME
doos attach [--net slirp|host|none] NAME [-- CMD...]
doos delete [--yes] NAME
Build: cmake -S . -B build && cmake --build build. Test: tests/run.sh.
Requirements: Linux >= 5.11, slirp4netns for the default network mode. On Ubuntu 24.04+ install the AppArmor profile once:
sudo cp apparmor/doos /etc/apparmor.d/doos && sudo apparmor_parser -r /etc/apparmor.d/doos
See SPEC.md (behavior, limits) and docs/RESEARCH.md (what works, measurements, known gaps).
Usage examples
doos get_or_create dev # created dev
doos attach dev # interactive shell as root inside
doos attach dev -- apt --version # run one command
doos attach --net none sandbox -- sh # no network at all
doos list
doos delete dev # dry run: shows what would go
doos delete --yes dev # really deletes
Container writes to /usr, /etc, /opt stay in the container (copy-on-write);
/root and /var are private and persistent. /tmp is memory-backed and lost on exit.
A container is running while its first attach command is alive; more attach calls
join it. Data persists until delete --yes.
Current limits you will hit
Tools run fine (curl, git, gcc, python3, pip, ping all verified). Package management does
not: apt-get update needs a seeded /var and -o APT::Sandbox::User=root, and
apt-get install cannot finish configuring packages because host-root-owned files are
unwritable and unchownable inside. Details, measurements and the fix are in
docs/RESEARCH.md (G7, "Field trial").
Configuration
| Variable | Meaning |
|---|---|
DOOS_HOME |
State directory (default ~/.local/share/doos). No , or : allowed. |
XDG_DATA_HOME |
Used as $XDG_DATA_HOME/doos when DOOS_HOME is unset. |
Troubleshooting
| Message | Cause and fix |
|---|---|
write /proc/<pid>/uid_map ... blocked or mount ...: Permission denied |
AppArmor restricts user namespaces. Install apparmor/doos (command above). |
slirp4netns failed to start |
Install slirp4netns, or use --net none / --net host. |
state path must not contain ',' or ':' |
Set DOOS_HOME to a plain path. |
container 'x' is running on delete |
Exit the attached command first. |
container limit reached (64) |
Delete one first. |
Safety summary
Host files are never written: system dirs are reached only through overlayfs. Host
/home, /sys and host loopback are not reachable in the default mode. --net host
removes network isolation and is opt-in. Known gaps (no cgroups, readable host /etc)
are listed with researched solutions (G1 to G6, not implemented) in docs/RESEARCH.md.
Project docs
| File | Content |
|---|---|
SPEC.md |
Behavior contract and limits |
docs/ARCHITECTURE.md |
Code map and flows |
docs/RESEARCH.md |
What works unprivileged, measurements, gaps |
AGENTS.md |
Rules for AI agents, release workflow |
CHANGELOG.md |
Release history |