§ 01 — OVERVIEW

subprocess.run()
for virtual machines.

Boot a Linux VM, run a command, collect structured JSON. Sessions exec in ~31ms, cold boots land in ~390ms P50 on an M3 Pro, and the sandbox is sealed by default — no host fs, no SSH, no escape hatch. Built for the agent loop. v0.7.1 hardens desktop boot — stable MAC across reboots, cancel-safe retry, pre-start crash delegate, live serial tail when the framebuffer's still dark.

get lumina → see desktop ↗

$ curl -fsSL abdul-abdi.github.io/lumina/install.sh | sh

macOS 14+ Apple Silicon Built on the native Virtualization framework. Linux host support on the roadmap.

$ lumina ps --watch — live · streaming

STATESIDIMAGEUPTIMEEXECSLAT

│ press q to exit · ? for keys —

Cold start (P50)

390ms

Exec latency

31ms

Live sessions

1,284

Execs / hr

847,312

§ 02

Watch it work — a session, start to stop.

LIVE / LOOPING

~/lumina demo

sid · b3a1-e4f7…

§ 03

Two shapes — one-shot or session.

CORE API

one-shot · disposable VM ~540ms

# boot, run, tear down. zero state.
$ lumina run "uname -a"

{
  "stdout": "Linux lumina 6.12-virt …\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 542
}

session · persistent VM ~30ms / exec

$ SID=$(lumina session start --memory 4GB \
       --forward 3000:3000 | jq -r '.sid')

$ lumina cp ./project/ "$SID:/work/"
$ lumina exec "$SID" --workdir /work "npm ci"
$ lumina exec --pty "$SID" "claude"

# many execs in parallel, ~30ms each.
# terminal restores on SIGINT — handled for you.

§ 04

Lumina Desktop — full-OS guests, with a face.

NEW IN v0.7.0

// app

A virtual Mac — for every OS you might want to try.

Two clicks from cold-launch to a booting Ubuntu installer. Sealed guest disk under ~/.lumina/desktop-vms/, shared with the CLI. Spin up, use, dispose — same primitive, with a screen.

Library · grid · sparklines · host ribbon
Wizard · OS tiles · BYO ISO/IPSW · drag-drop
⌘K fuzzy launcher · menu bar states
Fail-closed ISO integrity — app wizard AND lumina desktop create v0.7.1
Native fullscreen · per-VM window
Agent Images sidebar — custom lumina images create builds, one-click Terminal v0.7.1
Live serial tail during boot + crash — no more blank framebuffer v0.7.1
Stable MAC · stable DHCP lease · cancel-safe retry v0.7.1
USB-mass-storage CD-ROM for Windows · install-phase disk tuning v0.7.1

Ubuntu 24.04 LTS

ARM64 · ~2.7 GB ISO

Kali (rolling)

ARM64 · installer

Fedora 41

aarch64 · workstation

Debian 12

arm64 · netinst

Windows 11

ARM64 · BYO ISO

macOS 14+

IPSW · Apple Silicon

$ lumina desktop create --os-variant ubuntu-24.04 --iso ./*.iso

▷ CLI ↔ App share state · open the .app or stay in the terminal

§ 05

Stable primitives — what you can rely on.

CONTRACT / v0.7.1

lumina runone-shot

Disposable VM. Boots, runs, tears down. Per-invocation flags only — provisioning goes on session start.

--image · --volume · --workdir
--timeout · --env / -e
--copy · --download

session startpersistent

Spawns a long-lived VM. Returns a UUID-form SID. Provisioning belongs here, not on exec.

--memory · --cpus · --disk-size
--image (default · custom)
--forward host:guest · --volume

exec <sid>~30ms

Fresh shell per invocation. Multiple execs run in parallel on one session. No state persists.

--workdir · --env / -e
--timeout
--pty (REPLs, curses)

cptransfer

Explicit direction. Whichever side starts with <sid>: is the VM. Use this over virtio-fs for writes.

host ↔ guest
files & directories
auto-detected kind

pslisting

Live sessions. Piped output is JSON. Stale sockets surface as unreachable.

sid · image · uptime
active_execs
parse JSON, never TTY

desktop createv0.7.0

Make a .luminaVM bundle for a full-OS guest. Stages an installer ISO; ARM64 pre-flight rejects x86.

--os-variant · --iso
--memory · --cpus · --disk-size
--force (skip arch check)

desktop bootv0.7.0

Boot a .luminaVM bundle through EFI. Headless or windowed. macOS guests via desktop install-macos + IPSW.

--headless · --serial
--timeout · resumable install
Linux · Windows 11 ARM · macOS

exec --ptyraw bytes

Interactive TTY. Separate protocol from exec — raw byte stream, not envelope. For isatty() apps.

claude · vim · python3
one pty per session
raw mode · auto restore

§ 06

Output envelope — one shape, always.

CONTRACT

When stdout is a pipe, every run and exec emits a single JSON object. Success and error are disjoint — dispatch on the presence of the error field first. A non-zero exit_code is a successful exec, not an error.

// success● exit_code present

{
  "stdout": "hello\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 31
}

// error● error present

{
  "error": "timeout",
  "duration_ms": 30012,
  "partial_stdout": "starting…\n",
  "partial_stderr": ""
}

State

What happened

Recovery

Retry?

timeout

Command exceeded --timeout. partial_* present.

Longer timeout, or chunk the work.

Retryable

vm_crashed

Guest died mid-exec — OOM, kernel panic. partial_* present.

Session: session stop & restart.

Restart

connection_failed

vsock never came up. Command never ran; no partial_*.

Session is dead — restart.

Dead

session_disconnected

Control socket broke mid-exec. Only on exec, never run.

Reconnect or restart the session.

Reconnect

§ 07

Built for tight loops — the latency budget.

MEASURED / M3 PRO

Cold boot `true`

390ms

P50 — fresh VM to vsock-ready. P95: 558ms.

P50390ms

P95558ms

4× concurrent753ms agg

cold + first exec542ms

Warm exec

31ms

Warm session, true round-trip. 1ms stdev.

P5031ms

P9533ms

sustained100 exec/s

daemon RSS0 MB

Capacity

10×

Concurrent 512MB VMs on 18GB M3 Pro. Memory-bound, not framework-bound.

memory floor512 MB

default disk8 GB

vsock frame128 KB

kernellinux-virt

§ 08

Why agents need this — three shapes.

PATTERNS

— 01

┌────────┐ │ AGENT │ └───┬────┘ │ exec ▼ [ sandbox ]

Agents / the inner loop.

Claude Code, Cursor, OpenDevin — any agent running untrusted shell commands. One session, thousands of execs, full teardown when done. The session is the tab.

— 02

┌───┐ │CI │──┬──▶ run tests └───┘ ├──▶ build artifact └──▶ ship disposable × N

CI & Eval / reproducible runs.

Per-job VM, no cross-contamination between builds, exact resource ceiling. Fast enough to replace docker run in the hot path.

— 03

user ▸ lumina ▸ VM ┌─────┐ │ ??? │ └─────┘ sealed · audited · ephemeral

Untrusted code / user uploads.

Run code from users, plugins, or model output. Sealed guest — no host filesystem. --forward only binds 127.0.0.1. Audit via lumina ps.

§ 09

Get it running — three commands.

QUICKSTART

01INSTALL

$ curl -fsSL \
    abdul-abdi.github.io/lumina/install.sh | sh

One-liner installer fetches the signed CLI binary from the latest GitHub release and drops it in ~/.local/bin. macOS 14+ on Apple Silicon.

02FIRST RUN

$ lumina run \
    "echo hello from a VM"

Auto-pulls the default image (~30 MB) from GitHub Releases the first time. After that, every run gets a fresh APFS COW clone — no state crosses.

03SESSION

$ lumina session start \
    --memory 4GB

Captures the SID. Pipe to jq -r '.sid' and drive it from your agent.

— LUMINA_OUTPUT=ndjson opt-in remains for legacy consumers until v0.8.0 —

subprocess.run() for virtual machines.