Customer quickstart — ss in 8 commands

End-to-end onboarding for a new customer using ss to manage their own infrastructure. Each step is independent and re-runnable. Everything runs against your own account; nothing is shared with other ss users unless you explicitly publish.

0. Prereqs

git clone <your-celestial-fork>
cd <your-fork>
pnpm install
pnpm cli:link        # globally links the `ss` binary
ss --help            # smoke test

1. Create your account

An “account” is your local tenant — its own vault (encrypted secrets), its own module store, its own active-workspace pointer. Multiple accounts can live on the same laptop, switched explicitly.

ss account add my-company           # lowercase, hyphens, max 63 chars
ss account use my-company
ss account current                  # prints: my-company

Filesystem layout that gets created:

~/.starsystem/
  active-account                    ← pointer (one line: my-company)
  accounts/
    my-company/
      account.json                  ← metadata
      vault.db                      ← encrypted SQLite, account-scoped

Switching accounts (ss account use <id>) atomically flips every vault lookup, every active-workspace pointer (per repo), every provider-key resolution. No bleeds across accounts.

2. Pick a workspace

A “workspace” is a composition manifest at the repo root: <workspace-id>.<env>.ssws.yaml. It composes modules together into the effective service set for one environment.

ss workspace list                   # discover *.ssws.yaml in the repo
ss workspace use my-workspace.prod  # set the active pointer
ss workspace current                # prints: my-workspace.prod.ssws.yaml

The pointer lives at .starsystem/active-workspace in the repo root (gitignored — each dev picks their own).

3. Check readiness

ss onboard --env=prod

Reports four sections:

• Account — active + known
• Workspace — active + compose status
• Vault secrets — vault.required declared by each composed module vs what’s actually in the vault
• Provider tokens — per-provider keys (Hetzner, Supabase, etc.) the legacy onboarding flow knows about

--json mode emits a structured doc suitable for agent or web-UI consumption. Same data backs /onboarding in the dashboard.

4. Fill in workspace secrets

ss auth setup --env=prod

Walks through every missing vault.required key declared in any composed module. Per-key prompt includes:

• Which module(s) need it
• A human description (if the module’s manifest declared vault.descriptions)
• A provider hint when the key prefix maps to a known provider (SUPABASE_* → supabase, CLOUDFLARE_* → cloudflare, …)

Empty paste = skip. Re-run to continue where you left off.

5. Mint scoped provider tokens

For providers where ss can drive a paste/device flow, use the per-provider auth handler instead of set-secret — you get a deep link to the right dashboard page and automatic validation:

ss auth supabase                    # paste flow
ss auth fly                         # device flow (no paste needed)
ss auth cloudflare --scope=pages    # narrow Pages-only token

Cloudflare in particular: prefer narrow scopes (--scope=pages | r2 | workers | dns) over the broad api_token. The artifact deploy path prefers cloudflare/<capability>_token over the broad fallback.

ss auth status shows the full picture per provider:

ss auth status                      # all providers
ss auth status cloudflare           # one provider in detail

6. (Optional) Compose published modules

ss module search "scribe"           # find published modules
ss module info scribe@latest        # metadata-only view
ss module install scribe@latest     # add to your account's module store

Installed modules become resolvable from your workspace’s .ssws.yaml:

modules:
  - account: scribe@latest          # pulls from your local module store

Installs don’t require any auth — the registry is public-read. Publishing requires a Celestial-issued platform key (out of scope for customers; see internal docs).

7. Deploy

ss artifact deploy my-service.api --env=prod

Dispatches by target.type:

• VPS (hetzner, external) — builds a node tarball, scp’s it, atomic symlink flip, systemd restart
• cloudflare-pages — direct-uploads _artifact.include_paths to the named Pages project, binds custom domain
• Other (supabase, railway, …) — provisioner-specific

ss artifact build / push / pull / list / rollback are available for finer-grained operations.

8. Local daemons (optional)

For services with target.type: local-process in their manifest (e.g. dev servers that should auto-start at login):

ss processes ls                     # show declared local services
ss processes up <id>                # start one
ss processes enable-at-login        # launchd plist / systemd-user
                                    # boots them on session start

Wraps @celestial/process-manager — port-probe + lockfile re-attach detect externally-started daemons so re-runs are idempotent.

---

What’s where

Concept	Lives at	Per
Account metadata	~/.starsystem/accounts/<id>/account.json	Account
Vault	~/.starsystem/accounts/<id>/vault.db	Account
Active account pointer	~/.starsystem/active-account	Machine
Module store	~/.starsystem/modules.sqlite	Account-tagged rows
Inventory + tf_state	~/.starsystem/inventory.db	Machine (workspace-tagged rows)
Active workspace pointer	<repo>/.starsystem/active-workspace	Repo
Workspace manifest	<repo>/<workspace>.<env>.ssws.yaml	Repo

The 8 commands, condensed

ss account add my-company           # 1
ss account use my-company           # 2 (could be one step with --use flag, future)
ss workspace use my-workspace.prod  # 3
ss onboard --env=prod               # 4
ss auth setup --env=prod            # 5
ss auth <provider> [--scope=…]      # 6 (per provider that needs a real flow)
ss module install <id>@<v>          # 7 (optional)
ss artifact deploy <svc> --env=prod # 8

If you can recite these in order, you can onboard a new customer in under five minutes.

Troubleshooting

• “could not load workspace” → ss workspace use <id> or pass --workspace-file=<path>
• “vault is empty” → switched accounts; check ss account current
• “requires a platform key” → you tried ss module publish; customers use ss module install (publishing is internal-only)
• ss --help shows extra “PUBLISHER” section → your account has a Celestial team key; this is correct for internal users