Throwaway Linux VMs,
native on your Mac.

📖 Overview

Ciderbox is a fork of crabbox stripped to a single provider: Apple's native container CLI. Instead of routing through Docker Desktop, OrbStack, or a remote broker, ciderbox spins up real Linux VMs directly on your Apple Silicon hardware — using the same hypervisor that powers macOS virtualization.

The result is a tight local loop: init a project, write a .ciderbox.yaml, run ciderbox compile-test, and get a pass/fail result from an isolated Linux VM. Add more distros when you need a matrix — no cloud account, no per-minute billing, no daemon socket to babysit.

What you get

✅ Requirements

Install Apple container CLI

# Download the latest .pkg from GitHub releases
$ open https://github.com/apple/container/releases

# Install and start the system service
$ sudo installer -pkg container-*.pkg -target /
$ container system start

# Verify
$ container --version

📦 Install

Homebrew tap

$ brew tap mentholmike/ciderbox

From source

$ git clone https://github.com/mentholmike/ciderbox.git
$ cd ciderbox
$ go build -o ciderbox ./cmd/ciderbox
$ sudo install -m 0755 ciderbox /usr/local/bin/ciderbox

Verify the source install

$ ciderbox doctor
# checks: Apple container CLI, SSH keys, macOS version

🚀 Quick Start

Run this after ciderbox --version works locally from the source install above.

1 — Start in any project directory

$ mkdir -p /tmp/cider-demo
$ cd /tmp/cider-demo
$ ciderbox init
# creates .ciderbox.yaml in the directory where you ran it

Ciderbox treats the current directory as the project root. During a run, it syncs that directory into the VM under a workdir like /work/ciderbox/cider-demo, then executes your command there.

2 — Use one distro first

Edit .ciderbox.yaml:

project: cider-demo
compileTest:
  distros:
    - name: debian
      image: debian:bookworm
  command: "pwd && uname -a"
  parallel: false
commands:
  build: "make build"

3 — Run the test environment

$ ciderbox compile-test
# sync: /tmp/cider-demo -> /work/ciderbox/cider-demo
# ubuntu ✓ passed
# /work/ciderbox/cider-demo
# Linux ciderbox-abc123 ... aarch64 GNU/Linux

4 — Run a one-off command

$ ciderbox run -- pwd
# /work/ciderbox/cider-demo

5 — Knock it down

$ ciderbox chop
# terminated active ciderbox VMs

🧪 Distros Tested / Supported

Start with one distro while you are proving the loop. When the command is stable, add the rest to compileTest.distros and turn on parallel: true.

compileTest:
  distros:
    - name: debian
      image: debian:bookworm
    # - name: ubuntu
    #   image: ubuntu:26.04
    # - name: alpine
    #   image: alpine:latest
    # - name: fedora
    #   image: fedora:latest
    # - name: rocky
    #   image: rockylinux:9
  command: "make test"
  parallel: true

⌨️ Command Reference

⚙️ Configuration

All project config lives in .ciderbox.yaml at your repo root. Run ciderbox init to generate a starter file.

Starter schema

project: my-project

compileTest:
  distros:
    - name: debian
      image: debian:bookworm
  command: "make test"
  parallel: false
  dependencies: [build-essential, libssl-dev]  # optional

commands:
  build: "make build"

run:
  provider: apple-container
  image: debian:bookworm

Runtime dependencies

The dependencies key installs packages at VM boot before your command runs. Ciderbox detects the available package manager and supports apt-get, apk, dnf, yum, pacman, and zypper. On Debian/Ubuntu this translates to:

apt-get update && apt-get install -y --no-install-recommends \
  build-essential libssl-dev python3 && make test

Alpine uses apk add, Fedora/Rocky use dnf or yum, and openSUSE uses zypper. See Distros Tested / Supported when you want to expand from one image to a matrix.

🌿 Orchard — AI Agent Swarm

Orchard is a swarm management layer built on top of ciderbox VMs. It spins up a fleet of identical Linux VMs ("trees"), installs an AI agent runtime on each, and coordinates distributed workloads across them.

Demo — start to finish

$ mkdir -p /tmp/orchard-demo
$ cd /tmp/orchard-demo
$ ciderbox orchard init
$ ciderbox orchard plant
# Planted 1/1 trees.

$ ciderbox orchard graft --all
# installs Node 22 + OpenClaw, writes identity + openclaw.json
# validates OpenClaw config inside each tree

$ ciderbox orchard run --task "inspect this tree"
$ ciderbox orchard run -- "inspect this tree"
$ ciderbox orchard harvest --output results.json
$ ciderbox orchard press --input results.json

$ ciderbox orchard chop --yes
# Chopped 1/1 trees.

.orchard.yaml

name: my-orchard
trees: 1
template:
  image: debian:bookworm
  cpus: 2
  memory: 2G
agent:
  identity: archimedes-clone
  skills: []
  model: CHANGE_ME
  command: cd "${ORCHARD_WORKSPACE:-/root/.openclaw/workspace}" && openclaw --log-level silent agent --local --agent main --message "$ORCHARD_TASK"
secrets:
  envFile: .orchid.env
  required: []
workspace:
  sync: true
  path: /work/ciderbox

What we verified

The v1.0 smoke planted a Debian tree through Apple Container, grafted Node 22 and OpenClaw 2026.6.5, generated openclaw.json, ran openclaw config validate inside the tree, then chopped the tree cleanly.

🔍 How It Works

Ciderbox is a Go CLI that wraps Apple's container binary. There is no broker, no cloud account, no daemon socket — just your Mac's hypervisor.

Each VM gets its own IP address (no port mapping), boots from a cached image, receives your project files via a tar stream, runs your command, and is torn down on exit. The directory name becomes the default project workdir; if you run it from /Users/alice/src/api, the VM side is effectively /work/ciderbox/api. The run --keep flag keeps a VM alive for repeated checks or inspection.

🦀 vs Crabbox

Ciderbox is a focused fork — it does less, but does it without dependencies.

🛠 Troubleshooting

"apple-container provider not found"

The Apple container CLI isn't installed or the system service hasn't started.

$ sudo installer -pkg container-*.pkg -target /
$ container system start
$ ciderbox doctor   # should pass now

"container stopped before network address assigned"

The image exited before Ciderbox could prepare the workspace. Try a standard base image first, then add project dependencies through dependencies.

"No active ciderbox containers found" after chop

$ ciderbox chop
# terminates active ciderbox VMs

📋 Changelog

v1.0.0 — Ciderbox is Born

Forked from crabbox to focus exclusively on Apple Silicon native containers. No Docker, no cloud brokers, no SSH bootstrap — just container run and go.

• Apple container CLI provider for sub-second Linux VM boots
• Direct container IP networking — no port collision, no port publishing
• compile-test command for first-class multi-distro testing
• orchard command suite for AI agent swarms
• .ciderbox.yaml project configuration format
• Homebrew tap: brew tap mentholmike/ciderbox

v0.2.0 — Orchid

Added the orchard command suite for distributed AI agent workloads. Uses container exec (no SSH required for tree management). Supports swarm manifests via .orchard.yaml.

v0.1.0 — Initial Fork

Forked from crabbox, stripped to apple-container provider only. Added compile-test for multi-distro testing, build for single-distro builds, and chop cleanup. Fixed shell command parsing and added macOS 26 version gate.