Pullrun: Unified Execution for OCI Images

Pullrun is a next-generation runtime that allows a single OCI image to be deployed across multiple execution environments—including standard Linux containers, Firecracker microVMs, Apple Silicon VMs, Kubernetes workloads, and AI agent tasks—without needing separate image formats.

---

⚡ What is Pullrun?

At its core, Pullrun reimagines how images are stored and distributed. It replaces overlayfs with a content-addressed Directed Acyclic Graph (DAG). This enables zero-copy mmap reads and ensures that data is deduplicated by content hashes, remaining byte-identical across all nodes.

The Problem: Modern infrastructure is fragmented. We use Docker for local development, containerd for production, Firecracker for high-isolation, and CRI for Kubernetes. Despite all using OCI images, each has a distinct operational model and storage requirement.

🎯 Key Differentiators

Additional Integrated Capabilities:

• Kubernetes: Beta CRI shim support.
• Orchestration: Native Docker Compose compatibility.
• AI Integration: Built-in MCP server for agents.
• Security: Policy engine supporting Cosign, SBOM, and seccomp.
• Encryption: Secrets protected via $\text{AES}_{256\text{-GCM}}$.

---

📦 Installation

Get started quickly with a single command: curl -fsSL https://github.com/pullrun/pullrun/raw/main/install.sh | bash

Platform-Specific Details

• macOS: Installed via Homebrew $\rightarrow$ provides a native binary (no Xcode required).
• Linux: Available via APT or direct download $\rightarrow$ includes systemd service (needs /dev/kvm for VMs and runc for containers).
• Windows: pullrun.exe with automated WSL2 provisioning, runc, and Firecracker.

Manual Setup Options

• macOS (Homebrew):

  brew tap pullrun/tap
  brew install pullrun
  

• From Source:

  make build
  export PATH="$PWD/bin:$PATH"
  

• Cross-compiling for Windows:

  cd cli/pullrun
  GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o pullrun.exe .
  

---

🚀 Quick Start Guide

Basic Image Operations

• Fetch an image: pullrun pull alpine:3.18 (Benchmark: ~968ms)
• Build and Push (No Docker daemon needed):

  pullrun build ./Dockerfile -t myapp:latest --platform linux/amd64,linux/arm64
  pullrun push root-digest ghcr.io/myorg/myimg:latest
  

• Air-gapped Transfer: pullrun save digest -o myimage.tar $\rightarrow$ pullrun load -i myimage.tar

Running Workloads

Depending on your OS and desired isolation, use the following commands:

1. Linux Container pullrun run alpine:3.18 --cmd "echo" --cmd "hello pullrun"

2. MicroVM (Linux/macOS) pullrun run alpine:3.18 --backend vm --cmd "echo" --cmd "hello" --attach -t

3. Apple Silicon VM (macOS Default) pullrun run alpine:3.18 --cmd "echo" --cmd "hello pullrun" --attach -t

4. Windows (WSL2) pullrun.exe run alpine:3.18 --cmd "echo" --cmd "hello pullrun"

Advanced Lifecycle Management

• Interactive Shell: pullrun run alpine:3.18 --tty --attach --cmd /bin/sh (Use Ctrl-P Ctrl-Q to detach while the process continues)
• Re-attaching/Executing:
  • New PTY: pullrun exec id -t /bin/sh
  • Direct I/O stream: pullrun workload run id
• Background Tasks: pullrun run alpine:3.18 --cmd /bin/sleep --cmd 3600
• Management:
  • pullrun list (View all pending/running/exited tasks)
  • pullrun stop id (Terminate a workload)
  • pullrun images (List local DAG store contents)
  • pullrun rmi alpine:3 (Remove image)

Compose Support

Using the pullrun-compose binary:

# Standard containers (Linux default)
pullrun-compose up -f myapp/compose.yml

# VM-isolated workloads
pullrun-compose up -f myapp/compose.yml --backend vm

# Management
pullrun-compose logs -f
pullrun-compose down