Local Runtime

Maintainer-only. This local stack develops and proves the hosted SPAPS service; it is not the customer offer and does not grant backend operation, deployment, or redistribution rights. Start with Licensing and access.

spaps local can run against repo-native Docker assets or a bundled portable runtime shipped with the npm package.

Runtime Source Modes

spaps local --runtime-source <mode> supports:

Mode	Behavior
`auto` (default)	Use repo runtime when inside the `sweet-potato` checkout; otherwise use bundled runtime
`repo`	Force repo Docker assets (`docker-compose.spaps-dev.yml`)
`bundle`	Force packaged runtime assets from `spaps/assets/local-runtime`

Portable runtime directory defaults to ~/.cache/spaps/local-<port>. Override with --runtime-dir.

Data Source Modes

spaps local --data-source <mode> controls base database state:

Mode	Behavior
`empty` (default)	Start from empty local DB and apply migrations
`prod-cache`	Restore cached production dump, then reuse until signature changes
`prod-fresh`	Fetch a fresh production dump, restore, then boot
`--from-backup <path>`	Restore a specific `.sql.gz` dump file before API boot

Restore order is base dump first, migrations after API startup.

prod-cache, prod-fresh, and --from-backup can copy production-derived data onto a workstation. Use them only with explicit data-owner authorization, approved credentials, an encrypted local disk, a retention/deletion plan, and a dump confirmed to meet your PII sanitization policy. Prefer empty for normal development. Never use an arbitrary personal backup or share restored data.

Common Startup Patterns


npx spaps local
npx spaps local --runtime-source repo --data-source prod-cache
npx spaps local --runtime-source repo --fresh --data-source prod-fresh
npx spaps local --from-backup ~/.cache/spaps/db/prod.sql.gz
npx spaps local --runtime-source bundle --runtime-dir ./.skillbox/spaps-local

Operational Flags

Flag	Purpose
`--fresh`	Tear down and rebuild local runtime before boot
`--detach`	Start without tailing logs
`--open`	Open `http://localhost:<port>/docs` after startup
`--port <port>`	Choose API port (default `3301`)
`local stop`	Stop runtime and clean up compose stack

Health And Diagnostics


npx spaps status
npx spaps doctor --json
npx spaps verify --json

doctor checks environment prerequisites and probes domain routers to confirm mounts.

Runtime selection and local-mode hints are also visible via npx spaps quickstart --json.

Troubleshooting

If startup fails due to stale state, retry with npx spaps local --fresh.
If deterministic runtime files are needed (CI/managed environments), pin --runtime-source bundle --runtime-dir <path>.
If auth commands fail while local mode is off, provision with spaps create plus SELF_SERVICE_PASSWORD, or enable local-mode workflow in backend setup.

/packages/spaps-cli for command families, auth flow, fixtures, and domain control-plane commands.
/operations/troubleshooting for backend operational failures outside CLI runtime control.