OKLMdocumentation v1.0.3
On this page

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), and CLONE_NEWNET unless 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);
    • setrlimit bounds 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.
  • 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), the bypass mode is refused, and every command call asks unless a rule allows it. oklm doctor reports 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.