ADR-0011: Sandbox per platform
Records how the commands the harness runs are confined on each platform, and what happens where confinement is not available.
Status: accepted (2026-11-01).
Implementation notes (2026-11-01): on Linux everything above is in
place. The deny-rule paths are taken when each command starts (wildcard
rules expanded by a bounded walk). The process count is limited only
inside the user namespace, where the kernel (5.14 and later) counts the
sandbox's processes; outside it RLIMIT_NPROC would count
all the user's processes, so the unconfined fallback leaves it unset. On
Windows the Job Object carries the memory, process and CPU-time limits;
the restricted token and the low-integrity ACLs are not implemented, so
a command asked to be confined is refused there.
Context
Permission rules (ADR-0010) decide which calls run, but an allowed command can still do more than its text suggests: a build script, a test or an installer reads and writes wherever the user can. A sandbox bounds what a running command can reach, so a wrong or manipulated call does limited harm. OKLM targets Linux and Windows, depends only on the C library and nilorea, and must run without root or administrator rights.
Decision
- Linux: each command runs in a child created with
unprivileged user namespaces
(
unshare(CLONE_NEWUSER | CLONE_NEWNS | CLONE_NEWPID | CLONE_NEWIPC), andCLONE_NEWNETunless the call is allowed network access):- a new mount namespace where
/is bind-mounted read-only, the project and its added directories read-write, a private/tmp, and paths a deny rule names hidden (an empty file or directory mounted over them); setrlimitbounds on CPU time, address space, file size, open files and processes, set from the tool's limits;PR_SET_NO_NEW_PRIVS, then a seccomp filter refusing the calls that escape or reconfigure the sandbox (mount,unshare,setns,ptrace,bpf,keyctl, loading kernel modules);- the child is the leader of its own process group, so a timeout or a cancel kills everything it started.
- a new mount namespace where
- Windows: each command runs in a Job Object (limits on memory, processes and CPU time, kill on close of the last handle, so nothing outlives the harness unless detached, ADR-0012) under a restricted token with a low integrity level; the project and the added directories are given a low-integrity ACL entry the first time they are used, so they are the only writable places. Network access is not confined.
- Unavailable sandbox: where user namespaces are
disabled (some distributions, containers) or the Windows calls fail, the
harness says so at start; commands then run with the limits only
(
setrlimit, or the Job Object), thebypassmode is refused, and every command call asks unless a rule allows it.oklm doctorreports which parts are active. - File tools (Read, Write, Edit) run inside the harness, not in a child: the permission rules and the path normalization of ADR-0010 confine them.
Consequences
The Linux sandbox needs no helper binary and no privileges, but
depends on kernel settings the harness cannot change; it is tested with
a suite of escape attempts (writing outside the project, reaching a
hidden path, leaving the process group, raising limits, network without
permission). Amended 2026-11-03: without the network, the allowed
domains are reached through an HTTP proxy outside the sandbox, over a
Unix socket a relay inside the command's network namespace connects to
(no helper binary, no privileges; the filter is by host name, so a tool
that ignores the proxy variables still reaches nothing). Windows
confinement is weaker (no network or read confinement); the
documentation says so, and the default mode there keeps asking for
commands. macOS is not a target; its sandbox-exec profile
could be added behind the same interface.