doos/SPEC.md

doos specification

Authoritative description of behavior and limits. Code constants live in src/spec.hpp; change both together.

CLI

Command	Behavior
doos list	Table of NAME, STATE (running/stopped), NET, IMAGE (host when none), SIZE (cap), AGE.
doos get_or_create [OPTIONS] NAME	Creates the container if missing. Prints created NAME or exists NAME.
doos attach [OPTIONS] NAME [-- CMD...]	get_or_create, then run CMD (default /bin/bash, else /bin/sh). Starts the container if stopped, joins it if running. Exit code is the command's.
doos delete [--yes] NAME	Dry run unless --yes. Refuses a running container.
doos image list	Installed images (SIZE, IDS) plus catalog entries marked available.
doos image add [--sha256 HEX] SOURCE [NAME]	Installs an image. See Images.
doos image delete [--yes] NAME	Dry run unless --yes. Refuses an image used by any container, even with --yes.

get-or-create is accepted as an alias.

Container options (all four commands that take NAME-creating options: get_or_create, attach):

Option	Meaning	Default	Changeable later
--image NAME	Start from an image instead of the host system. Missing catalog images are fetched on demand.	none (host mode)	no
--size SIZE	Cap for what the container writes (512m, 8g, 1t; k/m/g/t).	4g	yes, on any later get_or_create/attach
--net slirp|host|none	Network mode.	slirp	no
--ids single|subuid	Id mapping.	subuid when available, else single	no

Naming an option on an existing container with a different fixed value is an error, never a silent change.

Limits (hard caps)

Item	Cap
Containers	64
Images	16
Name	containers [a-z0-9][a-z0-9_-]{0,31}, images [a-z0-9][a-z0-9._-]{0,31} (: becomes -)
Command arguments	256
Open files inside	4096
/tmp, /run, /dev/shm	256m, 64m, 64m (tmpfs)
--size	64m to 1t
Size scan interval	10 s (floor, never faster)
Size scan entries	5,000,000
Image download	2 GiB, 900 s
Skeleton directories	200,000
/etc copy	50,000 files, 256 MiB
Id range per container	65536 ids (0 plus up to 65535 from subuid)
slirp4netns ready wait	5 s
Lock wait	5 s
Tree recursion depth	256

State layout

$DOOS_HOME, else $XDG_DATA_HOME/doos, else ~/.local/share/doos. Path must not contain , or :.

containers/NAME/{meta,pid,lock,seeded.*,rootfs/,layers/<dir>/{upper,work},private/{root,var,etc}}
images/NAME/{meta,rootfs/}

meta keys: net created version image ids size.

Container filesystem, host mode (no --image)

Path	Source
/usr /opt (and /bin /sbin /lib /lib32 /lib64 when real dirs)	overlayfs, lower = host dir, upper = layers/<dir>/upper, with a directory skeleton in the upper
/bin /sbin /lib... when host symlinks	same symlink recreated
/etc	private copy of the readable host files, made once at creation
/root, /var	persistent private dirs; /var pre-seeded with the apt/dpkg directories
/var/lib/dpkg	overlay of the host dpkg database (when the host has it), regular files copied into the upper, lock files pre-created
/tmp /run /dev/shm	tmpfs
/dev	tmpfs + bound null zero full random urandom tty, new devpts instance
/proc	own pid namespace; sys sysrq-trigger irq bus fs read-only; kcore keys timer_list masked
/sys, /home, everything else on host	absent

Why the skeleton and copies: host root-owned files appear as nobody inside the container. Container root cannot write into directories it does not own, nor open files it does not own for writing, nor hard-link them. The skeleton recreates every host directory as a container-owned directory in the upper layer (same mode, owner rwx added); the copies make the few files package managers rewrite container-owned.

Container filesystem, image mode (--image)

/ is one overlay: lower = images/NAME/rootfs (shared, never written), upper = layers/root/upper. /tmp /run /dev /proc are mounted over it as in host mode. The image is extracted under the same id map the container uses, so image files owned by root are owned by the container's root and nothing needs a skeleton or copies. LANG is C.UTF-8.

Images

SOURCE for image add:

Source	Resolution	Verification
alpine	latest-stable minirootfs from dl-cdn.alpinelinux.org, via latest-releases.yaml	sha256 from the yaml, over https
ubuntu, ubuntu-VERSION	newest ubuntu-base-*-base-ARCH.tar.gz of that release from cdimage.ubuntu.com (default 26.04)	sha256 from SHA256SUMS, over https
https://...	downloaded	--sha256 HEX required, otherwise rejected
a file path	read locally	verified when --sha256 is given; otherwise used with a printed note

http:// is refused. A mismatch deletes everything it downloaded. The tarball is extracted with tar -p --numeric-owner, excluding dev/*, inside a user namespace with the image's id mode. Architectures: x86_64 and aarch64 for the catalog.

Size cap

The parent process scans the container's writable data every 10 s (hard floor). At 80% it warns once on stderr. At 100% it freezes the container's cgroup (cgroup.freeze); processes stop, nothing is deleted. It thaws on its own once usage is below 95%. A second doos attach is not frozen, so the user can free space from inside. Without cgroup v2 delegation the cap only warns and says so at start.

Isolation

User, mount, pid, uts, ipc namespaces always; network namespace unless host. Id map: container 0 is the invoking user; with subuid ids 1..65535 map to the user's /etc/subuid range through newuidmap/newgidmap; with single nothing else is mappable. no_new_privs, core dumps off. pid 1 is a reaping init that forwards SIGTERM/SIGINT/SIGHUP/SIGQUIT and kills the container when the command exits. Container lifetime = the first attach command; later attaches join via setns.

Networking

• slirp: private netns, slirp4netns --configure --disable-host-loopback, DNS 10.0.2.3, outbound only, host 127.0.0.1 unreachable.
• none: private netns with loopback only.
• host: shares the host network namespace (no isolation, explicit opt-in).

Safety rules

• delete (containers and images) is dry-run by default, scoped to the store, refuses running containers and used images, never follows symlinks. Trees with subuid-owned files are removed from inside the id map.
• Unverifiable input is rejected: URL images without sha256, hash mismatches, bad names, bad state paths, missing slirp4netns or newuidmap when requested.
• Seeding and scans report what they skipped (unreadable skipped: N).
• A failed start kills the half-built container (no orphans); a failed image add leaves no partial image.