You decide what to run. SpacePilot decides how and where.
SpacePilot runs AI models on the machine in front of you and tells you honestly what fits before you download it. One surface, every modality: text and chat, embeddings, speech and transcription, and image — with a per-run measurement record for each. Work the machine cannot hold goes to a rented box with the same honesty checks on both sides. A CLI, a FastMCP tool server, and a zero-build web UI are three windows onto one state.
Works today on Apple Silicon (Metal) and extends cleanly to CUDA and CPU.
The /v1 surface is OpenAI-compatible, so anything that already speaks
chat/completions or embeddings can point at it.
Two things this project does not do:
- It does not guess. Every model card is either flown — a real, dated measurement on a named machine — on paper, with the cited source — or unflown, which the registry names as a rule applied to a parameter count. Most registries pretend the third category does not exist. This one puts a number on it.
- It does not hide behind an API. The
/v1OpenAI-compatible surface means other tools can use SpacePilot without learning a new format. The heterogeneity it manages (local Lance/CUDA/CPU, rented spot, remote box) is the point.
The narrow waist that makes this useful: SpacePilot is a decision layer and orchestration layer — not a model, not a serving framework. It reads your fleet, ranks what fits, and routes your work honestly. It never invents a number.
| surface | surface | route |
|---|---|---|
| Text | Apple Silicon | spacepilot run text, pinned MLX-LM route |
| Text (OpenAI-compatible) | Any | POST /v1/chat/completions |
| Embeddings | Apple Silicon | POST /v1/embeddings, 1024-dim |
| Speech (TTS) | Any | In-process Kokoro-82M ONNX |
| Transcription | Any | whisper.cpp, measured, working |
| Image | Apple Silicon | mflux, own venv, subprocess-only |
| Video | — | Not yet — routes exist, refuse with 501. Mock test-pattern real render is gone. |
The /v1 surface is specified in docs/design/INFERENCE-SURFACE.md.
Video here is real in name and honest in report: the engine routes exist as specs, and the CLI tells you that. It is the longer-term aim, not a description of this repo today.
uv tool install spacepilot # from PyPI — the canonical installOr with pip:
pip install spacepilotThen:
spacepilot probe # what this machine can run
spacepilot models list # which models run here, with the fit verdict
spacepilot doctor # check environment and dependenciesNo account, no API key, no port opened. Full setup guide:
docs/LOCAL-SETUP.md.
Start the combined web UI + API on localhost:
spacepilot serveThen open:
- Cockpit —
http://localhost:8088/cockpit— live hardware telemetry, the model hub, and the save spot-billing path. - Create Studio —
http://localhost:8088/create— the create surface. - Developer docs —
http://localhost:8088/docs.
The Cockpit and other pages reflect whatever this machine actually is — including the honest "we don't know" state when a probe returns no answer.
The CLI overlay of the first probe looks like the landing page's "fifteen seconds, start to measured": it asks permission before reading anything, it reports what it read, and it stays honest about gaps.
spacepilot probeWhat this returns on a given machine is a records entry in
registry/measurements/<your machine>/, timestamped, source-attributed, and
reusable. Nothing in that flow phones home.
┌─────────────────────────────────────────────────────────────────────┐
│ SpacePilot Platform Topology │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Compute Provider Modules (pluggable execution runtimes) │
│ ├── Local Host Driver — Apple Metal MPS / CUDA / CPU │
│ ├── Hardware Probe — auto-detects usable VRAM, names the source │
│ └── Rented spots, docks, and managed APIs (cost-accounted) │
│ │
│ 2. Generative Model Modules │
│ ├── LTX-Video 2.5, Wan2.1, HunyuanVideo — spec only; routes │
│ │ refuse 501 until real inference exists │
│ ├── Speech & VO — In-process Kokoro-82M ONNX │
│ └── Narrative — GGUF screenplay deconstruction │
│ │
│ 3. Agentic Protocol & Tool Modules │
│ ├── FastMCP tool server (`spacepilot/mcp_server.py`) │
│ ├── DocIR 2.0 Edit Protocol — byte-exact reversible patches │
│ └── WebSocket PTY bridge — live shell & worker streaming │
│ │
│ 4. UI Component Modules (zero-build, no bundler) │
│ ├── Create Studio `/create` │
│ ├── Cockpit `/cockpit` │
│ ├── Oven Swarm Kanban `/oven.html` │
│ └── Director NLE `/studio` │
│ │
└─────────────────────────────────────────────────────────────────────┘
spacepilot/ The package — CLI, FastAPI app factory, drivers,
daemon, registry, measurement store
├── drivers/ Per-runtime execution drivers — MLX-LM (text),
│ mflux (image), whisper.cpp (transcribe),
│ Kokoro (speech), GGUF (narrative)
├── api/routes/ 16 route modules; mutating routes go through
│ require_token; read-only stays open
├── engines/ Video DiT engine specs — none run inference yet
├── web/ Zero-build UI actually served by app.py (ships
│ in the wheel — a uv tool install used to 500)
├── registry/ The model registry: variants, provenance,
│ measurements, systems
│ registry/models + systems + measurements
├── docs/design/ The architecture and inference-surface docs
tests/ Pytest suite — do not trust a hardcoded count
in any doc, check CI for the current number
landing/ The spacepilot.dev landing (deploys to Vercel)
native/SpaceBar/ macOS menu-bar app (Swift), separate cadence.
Moved to motionvector-dev/spacebar (carve-out
landed 2026-09-24); this directory will be
removed once the extraction settles.
Environment variables are the interface, or any secrets manager. Never
commit secrets; .env.example is the reference of what a deployment needs.
export LOCAL_WORKER_TOKEN="your-token" # gated worker endpointsEvery endpoint that spends compute or creates assets is gated by
X-SpacePilot-Token. Read-only and telemetry routes stay open.
Surfaces worth knowing:
/v1/chat/completions— OpenAI-compatible chat/v1/embeddings— embeddings/api/compute/local-profile— hardware capability telemetry (usable VRAM with its source)/api/compute/models/recommended— task-based fit verdicts for this machine/healthz— dependency-free liveness/docs— the developer portal
spacepilot-mcp is a stdio MCP server for Cursor, Claude Code, and
Antigravity. The Studio process also hosts a loopback-only Streamable HTTP
transport at /mcp/v1/.
python -m pytest tests/ -qDo not trust a hardcoded test count in any doc — CI on the current main
is the number that counts. The suite covers the DiT engine specs (mock
renders only, honestly labelled), the working TTS/transcription/embedding
drivers, device probing, the /v1 surface, and the FastMCP tools.
Honest about what's in and what is not:
- Works now: hardware probing with named sources, model fit verdicts,
compatibility across 88 variants, runtime installs that show what they
will move before they move it, speech locally, OpenAI-compatible
/v1. - Not yet: video on your own silicon, scheduling across more than one ship at a time, a daemon that runs persistently outside the CLI.
- Adjacent, separate package later: SpaceBar (macOS menu bar app) ships its own release. A CLI install should not pull in a macOS tray app.
Issues and PRs welcome. Two rules from AGENTS.md that keep
this honest:
- Execution over ceremony. Skip bureaucratic process. Bias toward working code with receipts.
- Strict tests before implementation on production paths: reproduce red → fix green → refactor. Exploratory spikes are exempt until they land in production paths.
Run the tests locally before opening a PR. CI runs on a self-hosted lenovo runner and is the gate.
Apache 2.0 — same license as the registry's Apache-family model weights so everything under this roof stays redistributable.
- PyPI:
spacepilot - Source: motionvector-dev/spacepilot
- Landing: spacepilot.dev
- Docs portal: spacepilot.dev/docs
- Design paper: spacepilot.dev/paper
- Releases: motionvector-dev/spacepilot/releases