Pullrun
One OCI image. Any execution target. CLI + runtime under 25 MB.
Run the same OCI image as a container, Firecracker microVM, Apple Silicon VM, Kubernetes workload, or AI agent task. No daemon required. No overlayfs. No separate VM images.
⚡ 30-Second Install •
🚀 Quick Start •
🏗️ Architecture •
🎯 Why Pullrun? •
🗺️ Feature Map •
☸️ Kubernetes •
🤖 AI Agents
⚡ What is Pullrun?
Pullrun runs the same OCI image as a container or a VM. It stores layers in a content-addressed DAG (no overlayfs), syncs blocks peer-to-peer, and ships as a ~14 MB CLI + ~6 MB runtime daemon.
Why this matters: Modern infrastructure uses too many execution engines — Docker for dev, containerd for production, Firecracker for isolation, CRI for Kubernetes, MCP agents for AI. Each has its own image format, storage, and operational model — even though they all run the same OCI images. Pullrun collapses these layers into one runtime.
Key differentiators:
Containers and VMs from the same image — no separate VM build step, no separate VM image format
Content-addressed DAG store — zero-copy mmap reads, deduplicated by content hash, byte-identical across every node
P2P image distribution — one registry pull per cluster, rest sync peer-to-peer at LAN speed
~14 MB CLI + ~6 MB runtime daemon (stripped) — no daemon required by default (CLI-only pullrun run), optional daemon for background services
Also included: Kubernetes CRI shim (beta), Docker Compose support, MCP server for AI agents, policy engine (Cosign, SBOM, seccomp), P2P sync layer, and AES-256-GCM encrypted secrets — all in the same binary.
📦 Install
🚀 Quick Start
🎯 Why Pullrun?
🏗️ Architecture is Everything
Docker's overlayfs store is a filesystem overlay — CVEs in overlayfs (CVE-2023-0386, CVE-2023-32629) can let a container escape to the host. Pullrun's content-addressed DAG store stores layers as-is, verified by content hash. No overlayfs, no escape.
Pullrun also mitigates shared-kernel cross-container risks that aren't specific to any storage driver — for example, kernel page-cache bugs like CVE-2026-31431 ("Copy Fail") affect all containers sharing a host kernel, regardless of the storage backend. Per-VM kernel isolation (Firecracker, Apple Virtualization) fully contains these. The DAG store makes the VM path zero-cost: the same image, no separate VM build step.
Pullrun is also rootless by default — no sudo needed, no daemon listening on a TCP socket, no attack surface from a central dockerd.
🔥 The Only Runtime with Containers + VMs from the Same Image
Same image, any isolation level. No separate VM image build step. The OCI manifest IS the VM rootfs.
🧬 Content-Addressed DAG Store
Pullrun's store is built on rkyv + mmap. OCI layers are stored once, deduplicated by content hash, and mmap()'d directly — no tar extraction, no overlayfs, no dockerd process owning the data.
A sha256: digest is globally consistent. Every node that has pulled alpine:3.18 stores byte-identical files on disk. This makes P2P sync trivial: blocks are verified by content hash, transferred delta-only, and deduplicated across the entire cluster.
📊 By the Numbers
Benchmarks: single-node, cold cache, alpine:3.18 on Apple M3 (macOS 14) for Pullrun vs Docker Desktop 4.27. Container run latency measured from run command exit to workload PID alive. Apple VM boot measured to interactive exec prompt. Firecracker measurements on Linux x86_64 with KVM; warm pool configured with --vm-warm-pool-size 4. Pullrun daemon RSS measured after pullrun pull alpine:3.18 + pullrun run alpine:3.18 --tty --attach --cmd /bin/sh then detached. Docker RSS from docker run -d --name idle alpine:3.18 sleep 3600.
Benchmarked with hyperfine (≥10 iterations, mean ± stddev reported). The benchmark script lives at hack/bench.sh — run it yourself to reproduce the numbers.
✨ Features
🏃 Workload Lifecycle
pull, run, stop, exec, attach, list, logs, stats, events, inspect, prune, rmi, gc plus:
commit — create a new image layer from a running container's current filesystem. The DAG store computes the delta against the original image, producing a content-addressed layer.
diff — show file-level changes between a running workload and its original image. The store compares DAG trees to produce an add/modify/delete listing.
update — live resource limit changes (CPU millicores, memory bytes) without restarting the workload.
cp — bidirectional file copy between host and workload paths.
save / load — OCI-compatible single-file tarball export/import for air-gapped environments. Re-import produces identical content hashes.
login / logout — bearer token auth for private OCI registries.
🔧 Build
Native Dockerfile builder (FROM, RUN, COPY, ADD, WORKDIR, ENV, CMD, ENTRYPOINT) with content-addressed layer caching by instruction hash. Uses runc directly for RUN — no Docker daemon. Multi-platform builds via --platform linux/amd64,linux/arm64.
🏗️ OCI Kernel Images
Kernel binaries are first-class OCI content. pullrun kernel install downloads a vmlinux from an OCI registry into the DAG store. The --kernel-image flag lets any workload specify a custom kernel by OCI reference — same store-backed, content-addressed pipeline: verified by digest, cached forever, pushable to any registry.
🐳 Compose
Full Docker Compose-compatible workflow: up, down, logs, ps, build. Supports dependency ordering (topological sort), port mapping, environment variables, volumes (bind mounts), resource limits (CPU/memory), labels, and per-project bridge networks for isolation. Parses standard docker-compose.yml files via the compose-spec/compose-go library.
Each service can run as a container or VM — use --backend vm to boot all services as Firecracker microVMs from the same compose file, no changes required.
☸️ Kubernetes CRI
Drop-in CRI shim at cri/pullrun-cri/ — implement RuntimeService and ImageService from the Kubernetes CRI API. Maps pod sandboxes to pullrun workloads, supports RuntimeClass (pullrun-container / pullrun-vm), pod annotations for image/CPU/memory overrides, and streaming (exec, attach, port-forward).
A native control-plane stub lives in control-plane/: pullrun-controller (scheduler) + pullrun-agent (per-node deployer) communicating over gRPC. This is a v1 work-in-progress with etcd, .pullrun.local DNS, and admission control planned — but the wire protocol is stable today.
🤖 MCP AI Integration
Native Model Context Protocol server exposing 15 runtime operations as MCP tools — run, stop, exec, list, get, inspect, logs, stats, pull_image, list_images, build, push, prune, compose_up, compose_down plus MCP resources (pullrun://workload/{id}, pullrun://workload/{id}/logs, pullrun://store/info, pullrun://images). Works in stdio mode (for opencode, Claude Code, Cursor) or SSE mode (for remote agents via HTTP).
🔐 Policy Engine
Gate workloads before they run — built-in support for:
Cosign signature verification (Ed25519 key pairs, key ID matching)
SBOM evaluation (CVSS scoring, ban by license)
Seccomp profiles (default allowlist of ~50 syscalls, unconfined, or custom JSON)
Read-only rootfs — prevents runtime tampering (write only to --volume mounts)
no_new_privileges — blocks setuid and capset escalation
Policy is declarative: required_signature: true, max_cvss_score: 7.0, deny_licenses: ["GPL-3.0"]
Compose all four: --require-signature --readonly-rootfs --no-new-privileges --seccomp-profile default.
🌐 P2P Image Distribution
Nodes share image blocks peer-to-peer via gRPC + Bloom filters. One node pulls from the registry, the rest delta-sync from each other. Features: mDNS/discovery for zero-config LAN peer finding, Bloom filter cache to avoid redundant transfers, gossip protocol for peer state, delta computation, registrar service for peer tracking.
📡 Networking
User-defined bridge networks with IPAM, inbound/outbound port forwarding, DNS resolution, and iptables integration. Four modes per workload via --net: isolated (default for containers, loopback only with host proxy on 10.42.0.1), bridge (shared pullrun-br0 bridge, inter-workload communication), slirp (default for VMs, userspace NAT via slirp4netns — no bridge, no iptables), host (shares host namespace), none (no network). Isolation is enforced by the proxy, not per-workload VLANs.
🗝️ Encrypted Secrets
AES-256-GCM encryption at rest, decrypted into workload tmpfs at runtime. pullrun secret create/get/ls/inspect/rm — data stays encrypted on disk, only the runtime process can decrypt.
🔄 Export/Import
Single-file OCI-compatible tarball export for air-gapped environments. Re-import produces identical content hashes.
📊 Events & Observability
Real-time event stream via pullrun events — IMAGE_PULLED, WORKLOAD_STARTED, POLICY_DENIED, etc. Per-workload stats with CPU/memory. Prometheus metrics exporter built into the daemon. PrometheusRule alerting config in deploy/.
🧹 DAG Store Garbage Collection & Reference-Counted rmi
pullrun rmi removes an image by tag or digest with immediate cascade deletion of unreachable subtree nodes. Per-node refcounts (node.refcount sidecar files) preserve shared layers — a layer referenced by another image is never deleted until the last referencing image is removed. Crash recovery via recompute_all_refcounts on daemon startup rebuilds refcounts from all tagged image and workload roots.
pullrun gc reclaims unreachable DAG nodes (orphaned layers, manifests, blobs) that are no longer reachable from any tagged image or running workload. Features: dry-run by default (report only), --apply to actually delete, --force to bypass the 90% safety guard, op-lock protection for in-flight operations, VM kernel image pinning via kernel_image_digest. The store no longer grows forever.
🖥️ Interactive Shells
Full TTY support with detach/re-attach via Ctrl-P Ctrl-Q. Works across all backends (container, Firecracker VM, Apple VM). Detached workloads keep running — re-attach with pullrun exec --tty <id> /bin/sh. Even works on exited workloads (daemon starts a fresh sleep container).
❤️ Health Checks & Restart Policies
pullrun run --health-cmd 'curl -f http://localhost:80' — periodic health checks with configurable interval, timeout, and retries. --restart on-failure|always|unless-stopped controls automatic restart on exit. Health state is surfaced via pullrun inspect and pullrun events.
🗄️ VM State Persistence
Stopped VMs behave like hibernated machines — all writes preserved, restart on demand with exec. Backend specifics: Apple Virt rootfs persists via VirtioFS, Firecracker retains the ext4 image, Container (runc) rootfs is ephemeral (only --volume mounts survive). No re-pull needed.
🔐 Private Registries
pullrun login <registry> for bearer token auth. Daemon accepts --insecure-registry for plain-HTTP mirrors and air-gapped LAN caches.
☸ Kubernetes
Pullrun ships a CRI shim in cri/pullrun-cri/ that implements the Kubernetes Container Runtime Interface. It maps pod sandboxes to pullrun workloads and supports:
RuntimeClass — pullrun-container for runc containers, pullrun-vm for Firecracker VMs
Pod annotations: pullrun.io/image, pullrun.io/cpu-millicores, pullrun.io/memory-bytes
Streaming: exec, attach, port-forward
Image management via the DAG store
Deploy as a DaemonSet with manifests in deploy/:
🤖 MCP AI Integration
Any MCP-compatible AI agent (opencode, Claude Code, Cursor) can control pullrun through natural language:
The MCP server exposes 15 tools and 4 resource types. SSE mode for remote agents: pullrun mcp --sse :8080.
🌐 P2P Image Distribution
Each block verified by content hash before acceptance — no trust required.
🔧 Backend Comparison
🏗️ Architecture
The store uses DashMap<Digest, Arc<Mmap>> for lock-free concurrent reads — the first reader pays for mmap() + page faults, every subsequent reader is a single atomic load. The Rust workspace is eleven crates (store, oci, exec, vm, net, dns, vsock, sync, policy, runtime, init); the Go side is the CLI, CRI shim, compose, and control-plane stub.
📁 Project Layout
📚 Documentation
📄 Technical Report
A technical report describing the architecture is available in /paper and archived on Zenodo: https://doi.org/10.5281/zenodo.20679669
https://doi.org/10.5281/zenodo.20679669
📄 License
Apache 2.0 — see LICENSE. Contributions subject to CLA.md.
Built with Rust 🦀 and Go 🐹