Local Development

Local development should prove behavior without hitting real payment, email, wallet, or production data surfaces. The repo wraps that posture in Make targets, local-mode settings, startup safety checks, and test fixtures that keep the Python server path canonical.

Install dependencies


cd path/to/sweet-potato
make install

Prepare environment


cp .env.example .env
printf 'DEVELOPMENT_ENVIRONMENT=local\n' >> .env

Start the stack


make local-proof-up
curl http://localhost:3301/health
open http://localhost:3301/docs

local-proof-up is the portable public target: it creates the minimal local environment when needed and does not require a sibling control-plane checkout. Internal operators with ../.env-manager/sync.sh may use make local-up instead.

Run affected tests


make pytest

Local Personas

Local mode can select development users through _user or X-Test-User. The health endpoint reports the active local-mode state and hints at the local test application.


curl 'http://localhost:3301/health/local-mode'
curl -H 'X-Test-User: admin' 'http://localhost:3301/api/example'

npm Quickstart Path

Use npx spaps when you are wiring a frontend or Node app to local SPAPS before you build backend auth infrastructure. That path covers the portable local runtime, starter scaffolding, CLI auth, fixtures, and domain control-plane commands.


npx spaps
npx spaps local
npx spaps quickstart --json
npx spaps create demo-app --template react

See Packages, SPAPS CLI Quickstart, and Local Runtime for the npm package workflow.

Safety Model

Startup validation checks required settings, production URL policy, legacy API-key posture, CORS policy, webhook destination policy, self-service network boundaries, and production-credential leakage in non-production mode.

Do not run pytest directly in this repo. The canonical test command is make pytest, which uses the repo’s configured testmon and parallel behavior.