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 Pullrun is a single-binary OCI runtime that runs the same image as a container or a VM. It stores layers in a content-addressed DAG (no overlayfs), syncs blocks peer-to-peer, and fits in 12 MB.
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** 12 MB static binary**— no daemon required by default, optional runtime 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.
pullrun run alpine:3.18 --cmd "echo" --cmd "hello pullrun" --attach -t
pullrun run alpine:3.18 --backend vm --cmd "echo" --cmd "hello pullrun" --attach -t
pullrun run alpine:3.18 --cmd "echo" --cmd "hello pullrun"
pullrun.exe run alpine:3.18 --cmd "echo" --cmd "hello pullrun"
curl -fsSL https://github.com/pullrun/pullrun/raw/main/install.sh | bash
| Platform | What you get |
|---|---|
| macOS | |
brew tap pullrun/tap && brew install pullrun → native binary, no Xcode |
|
| Linux | |
APT package or direct download, systemd service (requires runc for containers, /dev/kvm for VMs) |
|
| Windows | |
pullrun.exe + WSL2 auto-provisioning, runc + Firecracker |
Manual install options #
brew tap pullrun/tap && brew install pullrun
make build && export PATH="$PWD/bin:$PATH"
cd cli/pullrun && GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o pullrun.exe .
pullrun pull alpine:3.18 # 968 ms — ~2x faster than Docker
pullrun run alpine:3.18 --cmd "echo" --cmd "hello pullrun"
pullrun run alpine:3.18 --backend vm --cmd "echo" --cmd "hello" --attach -t
pullrun run alpine:3.18 --tty --attach --cmd /bin/sh
pullrun run alpine:3.18 --cmd /bin/sleep --cmd 3600
pullrun build ./Dockerfile . -t myapp:latest
pullrun build ./Dockerfile . -t myapp:latest --platform linux/amd64,linux/arm64
pullrun push <root-digest> ghcr.io/myorg/myimg:latest
pullrun save <digest> -o myimage.tar
pullrun load -i myimage.tar
pullrun-compose up -f myapp/compose.yml # containers (default on Linux)
pullrun-compose up -f myapp/compose.yml --backend vm # same compose, VM isolation
pullrun-compose logs -f
pullrun-compose down
pullrun list # all workloads (pending/running/exited)
pullrun stop <id>
pullrun exec <id> /bin/echo hello
pullrun exec <id> -t -- /bin/sh
pullrun workload run <id>
pullrun images # list pulled images in local DAG store
pullrun rmi alpine:3.18 # remove an image, cascade-delete unreachable layers
pullrun rmi sha256:abc... # also works by digest
pullrun gc # dry-run — report what would be deleted
pullrun gc --apply # actually delete unreachable nodes
pullrun gc --apply --force # bypass 90% safety guard
pullrun events --types=WORKLOAD_STARTED,POLICY_DENIED
pullrun stats <id>
pullrun network create my-net --subnet 10.43.1.0/24
pullrun run alpine:3.18 --net bridge
pullrun secret create db_password - # from stdin
pullrun run myapp:latest --secret db_password
pullrun config create nginx.conf ./nginx.conf # from file
pullrun config create nginx.conf - # from stdin
pullrun run nginx:latest --config nginx.conf
pullrun diff <id>
pullrun inspect <id>
pullrun commit <id> myapp:snapshot
pullrun login ghcr.io
pullrun logout
pullrun mcp # stdio mode (for opencode, Claude Code)
pullrun mcp --sse :8080 # SSE mode (for remote agents)
pullrun-runtime daemon --sync-addr 0.0.0.0:9500
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.
| Backend | Isolation | Pullrun | Docker | Podman |
|---|---|---|---|---|
| Linux containers (runc) | Process | ✅ | ✅ | ✅ |
| Firecracker microVMs | Per-VM kernel | ✅ | ❌ | ❌ |
| Apple Silicon VMs | Per-VM kernel | ✅ | ❌ | ❌ |
| Windows WSL2 containers | Process | ✅ | ✅ | ❌ |
| Windows Firecracker VMs | Per-VM kernel | ✅ | ❌ | ❌ |
Same image, any isolation level. No separate VM image build step. The OCI manifest IS the VM rootfs.
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 pulledalpine:3.18
storesbyte-identicalfiles on disk. This makes P2P sync trivial: blocks are verified by content hash, transferred delta-only, and deduplicated across the entire cluster.
| Metric | Pullrun | Docker |
|---|---|---|
First alpine:3.18 pull |
||
| 968 ms | ||
| ~2 s | ||
| Container run latency | ~400 ms | |
| ~800 ms | ||
| Apple Virt VM boot | ~160 ms | |
| N/A | ||
| Firecracker VM cold boot | ~500 ms | |
| N/A | ||
| Firecracker VM warm pool | ~200 ms | |
| N/A | ||
| Idle daemon RSS | 24.6 MiB | |
| ~90 MiB | ||
| Binary size | 12 MB | |
| ~75 MB | ||
| Rootless by default | ✅ | ❌ (dockerd as root) |
| Central daemon | Optional | Required |
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
— run it yourself to reproduce the numbers.
hack/bench.sh
pull
, run
, stop
, exec
, attach
, list
, logs
, stats
, events
, inspect
, prune
, rmi
, gc
plus:
— 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.commit
— show file-level changes between a running workload and its original image. The store compares DAG trees to produce an add/modify/delete listing.diff
— live resource limit changes (CPU millicores, memory bytes) without restarting the workload.update
— bidirectional file copy between host and workload paths.cp
— OCI-compatible single-file tarball export/import for air-gapped environments. Re-import produces identical content hashes.save
/load
— bearer token auth for private OCI registries.login
/logout
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
.
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.
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.
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.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).
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)— blocksno_new_privileges
setuid
andcapset
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
.
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.
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
), (shared
bridge
pullrun-br0
bridge, inter-workload communication), (default for VMs, userspace NAT via slirp4netns — no bridge, no iptables),
slirp
(shares host namespace),
host
(no network). Isolation is enforced by the proxy, not per-workload VLANs.
none
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.
Single-file OCI-compatible tarball export for air-gapped environments. Re-import produces identical content hashes.
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/.
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.
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).
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
.
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.
pullrun login <registry>
for bearer token auth. Daemon accepts --insecure-registry
for plain-HTTP mirrors and air-gapped LAN caches.
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/:
kubectl apply -f deploy/runtime-daemon.yaml
kubectl apply -f deploy/serviceaccount.yaml
kubectl apply -f deploy/servicemonitor.yaml
Any MCP-compatible AI agent (opencode, Claude Code, Cursor) can control pullrun through natural language:
pullrun mcp
The MCP server exposes 15 tools and 4 resource types. SSE mode for remote agents: pullrun mcp --sse :8080
.
pullrun-runtime daemon --sync-addr 0.0.0.0:9500
pullrun-runtime daemon --sync-addr 0.0.0.0:9501 \
--sync-peers node-a.example.com:9500
Each block verified by content hash before acceptance — no trust required.
| Backend | Isolation | Platform | Boot Time | Best For |
|---|---|---|---|---|
| 🐧 Linux Containers (runc) | Process (namespace) | Linux, macOS, Windows (WSL2) | ~400 ms | Dev, CI/CD, dense packing |
| 🔥 Firecracker microVM | Per-VM kernel (KVM) | Linux x86_64, Windows (WSL2 x86_64) | ~500 ms cold / ~200 ms warm pool | Multi-tenant, untrusted workloads, compliance, fast-recycling sandboxes |
| 🍎 Apple Virtualization | Per-VM kernel (Hypervisor.framework) | macOS Apple Silicon | ~160 ms | macOS dev, Apple Silicon CI |
pullrun (Go CLI)
pull · run · build · compose · inspect
events · stats · network · secret · mcp
│
│ gRPC (UDS or TCP)
▼
┌─────────────────────────────────────┐
│ pullrun-runtime │
│ ┌──────────┐ ┌──────────────────┐ │
│ │ Store │ │ Executor │ │
│ │ (DAG) │ │ runc / VM │ │
│ │ └ rkyv │ │ └ VmPool (warm) │ │
│ │ └ mmap │ │ │ │
│ │ └ DashMap│ │ │ │
│ └────┬─────┘ └──────┬───────┘ │
│ │ │ │
│ ┌────┴────────────────┴────┐ │
│ │ Network │ │
│ │ IPAM · Proxy · DNS │ │
│ └──────────────────────────┘ │
│ │
│ Sync · Policy · Secrets · Metrics │
└──────────────────────────────────────┘
│
┌──────────┴──────────┐
│ Kubernetes │
│ CRI shim · Runtime │
│ Class · Prometheus │
└─────────────────────┘
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.
proto/ # Protobuf definitions (single source of truth)
runtime/ # Rust workspace — core data plane
pullrun-store/ # Zero-copy DAG store (rkyv + mmap + DashMap concurrent cache)
pullrun-oci/ # OCI client + DAG converter
pullrun-exec/ # Executor trait + runc wrapper
pullrun-vm/ # Firecracker + Apple Virt backends, warm VM pool (pool.rs), pullrun-init guest agent
pullrun-net/ # IPAM, proxy, DNS, iptables, slirp4netns
pullrun-dns/ # In-process DNS server for workload resolution
pullrun-vsock/ # Vsock transport layer for VM guest-host communication
pullrun-sync/ # P2P block sync (Bloom, mDNS, gossip)
pullrun-policy/ # Cosign, SBOM, seccomp gates
pullrun-runtime/ # gRPC daemon
cli/pullrun/ # Go CLI (cobra) — 30+ commands
cri/pullrun-cri/ # Kubernetes CRI shim
control-plane/ # Multi-node orchestration stub: pullrun-controller + pullrun-agent (v1 WIP)
cmd/pullrun-compose/ # Docker Compose-compatible CLI
deploy/ # K8s manifests, Prometheus rules, alerts
docs/ # Architecture, operations, policy, MCP
tools/ # Standalone smoke-test workspaces (apple-virt-exec, firecracker-smoke, etc.)
| Document | What You'll Find |
|---|---|
docs/ARCHITECTURE.mddocs/OPERATIONS.mddocs/POLICY.mddocs/WINDOWS.mddocs/ALL_MCP.mddocs/cross-node-dag-sync.mdA technical report describing the architecture is available in /paper and archived on Zenodo:
https://doi.org/10.5281/zenodo.20679669
Apache 2.0 — see LICENSE. Contributions subject to CLA.md.
Built with Rust 🦀 and Go 🐹