Getting started with Spacecraft

This page walks you from “no Spacecraft” to “a blueprint launched against a local model” in five minutes.

Install

Spacecraft is a TypeScript CLI distributed as @celestial/spacecraft-cli. The fastest local-dev install is from a checked-out monorepo:

git clone https://github.com/celestial-intelligence-agency/celestial-orchestration.git
cd celestial-orchestration
npm install
npm run build -w @celestial/spacecraft-cli
npm link -w @celestial/spacecraft-cli   # exposes `sc` on $PATH

Published packages on npm are coming. Track ADR-029 for the publish plan.

Verify:

sc doctor

That prints a snapshot of detected hardware, Python version, llama.cpp build status, and any models in ~/.celestial/models.

Scaffold a blueprint

Pick a starting template and emit a single blueprint.yaml:

sc blueprint --template chat-assistant --yes \
  --id my-helper --name "My Helper" --model phi3 -o blueprint.yaml

Templates: chat-assistant · tool-agent · rag-agent · telegram-bot.

For a full package (blueprint + manifest.json + checksums, ready for the hangar), use sc compose init instead:

sc compose init ./harnesses/my-helper \
  --template chat-assistant --inference vercel-ai --model phi3 --register
# --register installs the package into the local hangar

Dry-run before you launch

Always dry-run a new blueprint to inspect the resolved graph, engine choice, and adapter wiring — no LLM calls are made:

sc launch ./blueprint.yaml --dry-run
sc launch ./blueprint.yaml --dry-run --json    # machine-readable

The dry-run prints the engine resolution, the Starflow contract parity report (graph node + edge count), and exits.

Bring up an inference engine

Spacecraft is LLM-adapter agnostic — the same blueprint runs against any OpenAI-compatible endpoint. To run locally:

# Pull a model
sc pull ollama:llama3                        # → ~/.celestial/models/llama3.gguf
sc pull hf:TheBloke/Qwen2.5-7B/qwen.gguf     # HuggingFace GGUF

# Serve it
sc serve --model llama3                                # llama.cpp (CPU/Metal)
sc serve --model Qwen/Qwen2.5-7B-Instruct --backend vllm    # GPU, PagedAttention
sc serve --model Qwen/Qwen2.5-7B-Instruct --backend sglang  # GPU, RadixAttention

For cloud inference (Anthropic, OpenAI, Ollama Cloud) point the blueprint’s inference.baseURL + apiKey at the provider instead — no sc serve needed.

Launch

# From a local file
sc launch ./blueprint.yaml

# From the hangar (if built or pulled)
sc launch spacecraft://my-helper

# Interactive picker (lists hangar entries)
sc launch

Common flags: --model <name> · --adapter <id> · --engine <url> · --memory-adapter <id> · --strategy <name> · --bindings <path>.