Getting started with Starsystem

Starsystem turns a single YAML file into a working multi-service infrastructure — across 22+ providers — with rollback as a first-class verb. This guide gets you from clone to deployed in 10 minutes.

The thesis: every deploy Starsystem performs leaves a queryable, replayable, auditable artifact. ss inspect shows the receipts; ss rollback restores from them; OpenTelemetry traces propagate across surfaces.

Prerequisites

Node.js 22+
pnpm 9+ (or npm 10+ — the workspace uses pnpm by convention)
A starsystem.yaml file (or use the smoke-test fixture in examples/smoke-test/)

Install

git clone https://github.com/celestial-intelligence-agency/celestial-orchestration
cd celestial-orchestration
pnpm install
pnpm --filter @celestial/starsystem-cli build

# Make `ss` available globally
ln -s "$(pwd)/packages/starsystem-cli/dist/cli.js" /usr/local/bin/ss
ss --help

10 minutes

Minute 1 — pick the smoke-test fixture

The repo ships a self-contained fixture in examples/smoke-test/ that deploys a SQLite database and two local Node processes. No cloud credentials needed.

cd examples/smoke-test
cat starsystem.yaml          # base config
cat starsystem.dev.yaml      # dev-environment overlay

The base config defines services (app-db, api, worker) with descriptions and depends_on graphs. The overlay adds the actual deployment targets (sqlite for the db, local-process for the two processes).

Minute 2 — validate the config

$ ss validate --env=dev
starsystem validate  ─  dev
──────────────────────────────────────────────────────────────────

  ✓ starsystem.yaml      (3 services)
      No issues found

  ✓ starsystem.dev.yaml  (3 services)
      No issues found

──────────────────────────────────────────────────────────────────
✓ Configuration is valid.

ss validate runs the Zod schema (deep), checks depends_on and inject_from references, and detects circular dependencies. It’s the right thing to run in CI before any deploy.

Minute 3 — preview with `ss plan`

$ ss plan --env=dev
starsystem plan  ─  dev
──────────────────────────────────────────────────

  + app-db  sqlite         ·  will create
  + api     local-process  ·  will create
  + worker  local-process  ·  will create

──────────────────────────────────────────────────
Plan: 3 to create, 0 to update, 0 unchanged.

Run `ss provision --env=dev` to apply.

Three planned creates. No surprises.

Minute 4-5 — deploy

$ ss deploy --env=dev
starsystem deploy → smoke-test / dev

→ app-db via sqlite...
  ✓ SQLite database ready at ./data/smoke-test-dev.db
  Credentials written to vault: DATABASE_URL, SQLITE_PATH

✓ Deploy complete: 1 provisioned
  Run 'starsystem vault materialize --env=dev' to write .env.dev

Local-process services are excluded from deploy (they’re managed by the ss start / ss stop supervisor, not the cloud provisioner) — only the SQLite database gets materialized.

Minute 6 — receipts: `ss inspect`

$ ss inspect --env=dev
ss inspect ed060a44-5f97-461c-8ff6-3d8cae953092

  status:    ✓ completed
  duration:  11ms
  started:   2026-05-02 14:32:01 UTC
  ended:     2026-05-02 14:32:01 UTC

  ── Timeline ──
  ✓ ss.deploy.service.app-db        (11ms)

  ── Next actions ──
  Check drift         ss drift --env=dev
  Re-deploy           ss deploy --env=dev
  List deploys        ss inspect --list --env=dev

This is the receipts view — same shape as decider inspect for cross-product consistency. Pass --state to include the provision state snapshot, or --json for machine-readable output (for agents).

Minute 7 — drift detection

Pretend something changed in your config — bump the SQLite path:

$ sed -i '' 's|smoke-test-dev.db|smoke-test-dev-v2.db|g' starsystem.dev.yaml
$ ss drift --env=dev
○ app-db (sqlite) — drift: file moved from ./data/smoke-test-dev.db to ./data/smoke-test-dev-v2.db

ss drift compares your YAML against actual provider state. Use it to catch out-of-band changes (someone manually nudged a server, a vendor auto-updated something).

Minute 8 — rollback

$ ss rollback --env=dev --list
1   ed060a44-...  app-db   2026-05-02 14:32:01   current
2   97c6dfbc-...  app-db   2026-05-02 14:30:14   ok

$ ss rollback --env=dev --to=97c6dfbc
✓ Rolled back to deploy 97c6dfbc — credentials and overlay state restored.
  Note: infrastructure NOT re-provisioned. Run `ss deploy --env=dev`
  if dependent services need re-applying.

Rollback restores the vault credentials and overlay YAML state from the historical DeployRecord. It deliberately does NOT re-provision infrastructure — that’s the right division. ss deploy again to re-converge.

Minute 9 — telemetry

If you have an OTLP-compatible backend (Honeycomb / Axiom / Datadog / Grafana Tempo / your own collector), enable telemetry:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io/v1/traces
export OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=$HONEYCOMB_KEY

ss deploy --env=dev

Spans now propagate into your backend:

ss.cli.deploy (CLI-level)
ss.deploy (engine-level)
ss.provision.<provider> per service
ss.engine.compute.* (when calling external compute)

Trace IDs use W3C Trace Context, so when an agent calls Starsystem MCP from inside a Decider workflow, the cross-product trace links cleanly.

Minute 10 — graph render

$ ss graph render --services --format=mermaid > topology.mmd

Produces a Mermaid topology diagram of services + dependencies. Drop into a PR comment, a README, or any markdown.

What’s next

Three commitments that shape Starsystem

Schema-first config, not DSL — agents and humans both read the same YAML
Rollback is a verb, not an afterthought — every deploy is a snapshot you can restore
Receipts — every deploy and every state change is a queryable, replayable, auditable artifact

If anything in the product violates one of these, file a bug.