kern

_{Runs on Linux and ARM boards directly, on Windows through WSL2 and on a Mac through colima, Lima or OrbStack: the same binary and the same CLI under a Linux kernel. Install.}

What kern is

One binary that manages resources, of which isolation is the first. That is why there is no single row for kern in a comparison table: it is a container runtime, a sandbox, a resource slicer and a stack runner at once, in one static binary with no daemon.

• A real container. Real OCI images: pull, build from a Dockerfile, commit, push, save/load. A box from an image starts in ~3.4 ms.
• Sandbox an AI agent, one container per tool-call. The command it just decided to run, the snippet the model just wrote, a notebook cell, a CI step. kern starts a box, runs it, deletes it, fast enough that per-call isolation is the default. Network off unless you ask, memory and PID caps the kernel enforces, capabilities dropped, seccomp deny-by-default, timeout applied from the outside.
  Typed faults, not stack archaeology. Timeout, OOM-kill, blocked syscall, missing command: each returned next to stdout and the exit code. Branch on it and keep going.
  One binary, no daemon. Wire it from Python, Node, LangChain, or any MCP client below. And what it is not, because the boundary is the Linux kernel.
• Rootless, always. User, PID, mount, network, UTS and IPC namespaces, an overlay or read-only root pivoted in, a deny-by-default seccomp allowlist and cgroup v2 limits. One flag, --security-profile untrusted, is the whole hardened bundle.
• Resource profiles, not just isolation. CPU (vcpu:), memory, disk (vdisk:) and devices (vgpio:), declared once in a kern.toml and attached by name. kern run applies the same caps to a process on the host, with no sandbox at all, plus --landlock-rw <path> to confine that process's writes with the kernel's own LSM. docs/RESOURCES.md
• Stacks, in kern's own format or in the one you already have. kern compose <file> up takes a stack.toml ([box.NAME] tables, with the resource profiles above) or a docker-compose.yml, with no conversion step. One stack to one pod, services reaching each other by name.
• The tools around them. ps, logs, exec, stats, inspect, wait, top (a live TUI), doctor. The Python binding also plugs into LangChain twice: as a code tool, and as an execution policy for its shell middleware.

Its entire Rust dependency tree is libc: JSON and OCI manifests are parsed by hand, and pull shells out to the curl and tar already on the machine rather than linking a TLS stack.

Install

A box is made of Linux kernel features, so kern runs where there is a Linux kernel: Linux and ARM boards (Raspberry Pi · Jetson · Arduino UNO Q) directly, Windows through WSL2 with a pre-baked rootfs and an installer that sets WSL2 up for you, and a Mac inside a Linux VM (colima, Lima, OrbStack, UTM), where it is the ordinary Linux kern: same binary, same CLI, same behaviour as your CI box.

One static file, no toolchain. The script picks x86_64 or aarch64, installs to ~/.local/bin, and refuses a download whose SHA256 does not match. From source instead, the whole dependency tree is one crate:

Debian and Ubuntu, Fedora, the RHEL family (Rocky, CentOS Stream), openSUSE, WSL2, and ARM boards: any distribution with unprivileged user namespaces and cgroup v2. Each release runs the full suite on those, in real VMs and on the boards, before it ships.

docs/INSTALL.md has the rest: verifying the checksum by hand, KERN_INSTALL_DIR, the Windows and Mac guests step by step, and what the resource caps do on a default VM.

The binary and the SDK move separately. kern is versioned by its git tag, kern-sandbox by its own release, and the SDK drives the binary as a subprocess, so an SDK newer than the binary can ask for behaviour the binary does not have. kern --version and python3 -c "import kern_sandbox; print(kern_sandbox.__version__)" tell you what you have, and the changelog names the release each fix landed in.

Quickstart

--security-profile untrusted is the seccomp allowlist plus --cap-drop ALL plus --read-only, in one flag. kern ps and kern top show what is running; every verb that lists or inspects also answers --json, so nothing has to parse a table. One runnable example per thing kern does: examples/.

Run an agent's code: Python, Node, LangChain, MCP, pi

The bindings are how your program calls kern. The code inside the box can be in any language, because the box is an OCI image: Python, Node, Go and Rust all run with the same command and a different --image, and so does anything else that ships one.

An agent needs somewhere to run what the model just wrote. kern-sandbox is that place: a thin, dependency-free wrapper over the kern binary, called from your own program. On PyPI and npm; the API is in bindings/python/ and bindings/node/.

Every call is a fresh isolated box: network off, memory and pid caps, capabilities dropped, output bounded, and a timeout the binding enforces itself. A timeout, an OOM-kill or a blocked syscall comes back as a typed fault on the result rather than as an exception. code_stderr is that result's stderr without kern's own notes, which is what belongs in a context window.

It also ships kern-mcp, a dependency-free stdio server that gives Claude Desktop or Cursor a local code interpreter, and the server is stdio, so the same one line points a client at a box on another machine.

The rest is on the pages that own it, none of it repeated here: the full API, the rich-result capture, prewarming and the LangChain integration in bindings/python/README.md and bindings/node/README.md; every KERN_MCP_* variable and the remote form in docs/MCP.md; and, for the pi coding agent, kern-pi routing its bash, read, write, edit, ls, grep and find into a box, with a README that states which half is the kernel's boundary and which is a path check, in integrations/pi/.

Run a whole stack: your docker-compose.yml, unchanged

One file, one command. kern reads its own format, and it reads the docker-compose.yml you already have, unchanged.

Both official images start, web reaches db by service name, and the port is published. A compose file can also name kern's own things in the spec's extension namespace (x-kern-vcpu, x-kern-security-profile) and still run under Docker unchanged, because every other runtime ignores an x- field. A typo inside one is reported rather than dropped.

One constraint comes with the speed: a stack is one pod on one network namespace, so two services cannot both listen on the same container port even when their published ports differ. up refuses the collision by name before starting anything, and --no-pod lifts it by giving each service its own namespace with peers reachable by name.

Official images that drop to a non-root user want uidmap and an /etc/subuid line, and outbound pulls want pasta; kern doctor names either if it is missing. This is the local dev loop, not a production orchestrator. docs/DOCKER-COMPAT.md

Resource profiles

A slice is declared once in ~/.config/kern/kern.toml and attached by name, to a sandboxed box or a bare process, with the same token. Three kinds: vcpu: (CPU and memory), vdisk: (a size-capped scratch disk) and vgpio: (device nodes).

Profiles compose, an explicit flag beats a profile's own value, and every key is spelled like its CLI flag. A backend naming no declared pool is refused when the config is read, not when the box runs.

Two things this says out loud rather than letting you assume. A vdisk: is a RAM-backed tmpfs when kern runs rootless, whatever its backend says, and an ext4-on-loop image with a real quota when it runs privileged; kern reports which one you got, and the size cap binds either way. And vgpio: is chip-granular, not per-line: asking for pins binds the whole /dev/gpiochipN, which exposes every line of that controller, so pins = [17] is cooperative metadata rather than a boundary. Naming a device node grants that node and nothing else. docs/RESOURCES.md

kern vs Docker vs Podman: what a container costs, and what kern does not have

All three columns measured on one host, same workload, same day: an Intel i7-14700KF running Linux 7.0.0, with the method in BENCHMARKS.md.

Performance

Intel i7-14700KF, Linux 7.0.0, the release binary, alternating batches on an idle machine.

kern is ahead of bubblewrap by about 9%, and that gap is small enough that it only holds up under a method: BENCHMARKS.md has the alternation, the 240 batches, the aarch64 boards, why the release binary and not a local build, and every caveat. The gap that means something is the one to the engines, two orders of magnitude above.

Security

Namespaces, a pivot_root, 16 dangerous capabilities dropped before exec, an always-on seccomp allowlist (moby's default filter minus kern's 35 escape syscalls, which stay hard-killed; anything outside the vetted set returns ENOSYS), cgroup v2 limits that --require-limits refuses to start without, and a deny-by-default /dev. Where a boundary is cooperative rather than kernel-enforced, SECURITY.md says so and names the bypass.

You do not have to take it on trust. pentest/ holds five adversarial suites that assert those boundaries against the kernel rather than against kern's own reporting, with no registry account and no network:

Report a vulnerability privately via GitHub Security Advisories or [email protected].

Documentation

Status

The core is done and the CLI is frozen. 1073 Rust, 458 Python and 93 Node tests, clippy-clean and cargo-deny-clean, on Linux, WSL2, Raspberry Pi 5, Jetson Orin Nano and Arduino UNO Q.

A script written against the CLI keeps working: no verb, flag or --json field changes meaning inside a patch release. What changed in each one is in the changelog.

What kern is not

• Not a hypervisor. The boundary is the Linux kernel, so a kernel privilege-escalation bug is an escape. kern is for code you chose to run and whose blast radius you own, not for hostile code from strangers on a kernel you serve other tenants from.
• Not free of the userns trade. Its isolation is built on an unprivileged user namespace, a fertile source of kernel LPE bugs. SECURITY.md says so before any claim.
• Not a wall around what you mount in. -v $HOME:/host gives the box your home directory. --net host and --privileged are opt-outs by name.
• Not a Docker Engine reimplementation. The formats, not the API: no overlay networks, no plugins, no Swarm. docs/DOCKER-COMPAT.md
• Not a Kubernetes runtime. No CRI. Use containerd or CRI-O.
• Not shipping GPU slices. On the roadmap. kern doctor reports what a VRAM cap would be worth per GPU; on consumer hardware that is a cooperative quota, NOT a boundary against malicious code. Nothing intercepts a driver call and nothing caps a GPU.

Known gaps: ROADMAP.md.

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md has the workflow and the gates; contributions are covered by the CLA.

Maintainer

Alessandro Polito, @realexhub, Italy. Earlier commits carry @getkerndev, the account the project was published from.

License

Apache-2.0. See LICENSE and TRADEMARK.md.