# 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, AGE. |
| `doos get_or_create [--net M] NAME` | Creates the container if missing. Prints `created NAME` or `exists NAME`. |
| `doos attach [--net M] 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. |

`get-or-create` is accepted as an alias. Network mode `M` is fixed at creation: `slirp` (default), `host`, `none`.

## Limits (hard caps)

| Item | Cap |
|---|---|
| Containers | 64 |
| Name | `[a-z0-9][a-z0-9_-]{0,31}` |
| Command arguments | 256 |
| Open files inside | 4096 |
| `/tmp`, `/run`, `/dev/shm` | 256m, 64m, 64m (tmpfs) |
| slirp4netns ready wait | 5 s |
| Lock wait | 5 s |
| Delete 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,rootfs/,layers/<dir>/{upper,work},private/{root,var}}
```

## Container filesystem

| Path | Source |
|---|---|
| `/usr /etc /opt` (and `/bin /sbin /lib /lib32 /lib64` when real dirs) | overlayfs, lower = host dir, upper = `layers/<dir>/upper` |
| `/bin /sbin /lib...` when host symlinks | same symlink recreated |
| `/root /var` | persistent private dirs, no host data |
| `/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 |

## Isolation

User, mount, pid, uts, ipc namespaces always; network namespace unless `host`. Single-entry id map (container root = invoking user). `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` is dry-run by default, scoped to `containers/NAME`, refuses running containers, never follows symlinks.
- Invalid names, bad state paths and missing slirp4netns fail loudly.
- A failed start kills the half-built container (no orphans).