Local registry operator guide

Local registry operator guide

Spacecraft (sc) keeps a machine-local registry under your home directory. This is not the future Starsystem-hosted registry (ADR 021); it is the operator depot used today for sc launch spacecraft://…, sc hangar, and sc compose init --register.

Directory layout (~/.celestial)

Path	Purpose
registry.json	JSON index of models, spacecraft (harness bundles in the hangar), and skills entries. Written by RegistryStore.
hangar/	One subdirectory per registered spacecraft id (copied bundle: blueprint.yaml, harness.yaml, manifest.json, optional rag/, docs/, etc.). Populated by sc build / sc compose init --register / installHarnessPackageToHangar.
skills/	Global skill depot paths referenced from manifests.

Paths are created on demand when the CLI first touches the registry.

registry.json shape (conceptual)

The file is an object with arrays (see RegistryData in the repo: packages/spacecraft/cli/src/registry/types.ts):

• models — engine weights / aliases (e.g. GGUF path, source tag).
• spacecraft — { id, name, version, bundlePath, manifestPath, addedAt } for each hangar entry.
• skills — skill packages available for harness manifests.

Treat registry.json and hangar/ as one backup unit: restoring only JSON without matching hangar/<id>/ trees will break spacecraft:// launches.

Backup and migration

1. Stop any running sc launch / gateway processes using the hangar.
2. Copy ~/.celestial/registry.json and the entire ~/.celestial/hangar/ directory (and skills/ if you use skills).
3. On a new machine, restore to the same paths (or merge entries carefully—duplicate id values will collide).

Hosted publish (optional)

sc compose publish [dir] can POST a validated package to a URL you control. It is off by default:

• Set CELESTIAL_REGISTRY_PUBLISH_URL to an HTTPS endpoint that accepts POST with Content-Type: application/json.
• Optionally set CELESTIAL_REGISTRY_PUBLISH_TOKEN for Authorization: Bearer ….

Payload contract: hosted-publish/v0 — see packages/spacecraft/cli/src/compose/publish-hosted-registry.ts. Until Starsystem exposes a stable ingest API, expect to point this at your own stub or internal gateway.

Use sc compose publish --dry-run to print the target URL and approximate JSON size without sending traffic.

Related

• Starflow Harness Design
• Gateway + personal agent
• ADR 021 (repo): Starsystem registry control plane — /.product_mgmt/adr/021-ss-registry-control-sf-runtime-sc-facade.md
• ADR 030 (repo): Composable builder — /.product_mgmt/adr/030-composable-agent-builder-registry-cli-first.md