Skip to main content
Each Stralos repository is independent and generally uses pnpm. Check each repo README before running service-specific setup.

​
Node version

stralos-shell requires Node 24. The repository pins 24.19.0 in .node-version. Use a version manager that reads .node-version (for example fnm or nodenv) to match this exactly. The package.json engines field enforces >=24 <25.

​
Local ports

​
API service commands

Most API services support:
stralos-api-global also needs DynamoDB Local for OTP and sessions:
The .env.example sets OTP_EXPOSE_GENERATED=true by default. This causes POST /auth/otp/request to include the generated six-digit code in its JSON response, which is necessary for completing the login flow locally because SES email delivery is disabled (SES_ENABLED=false). See Local OTP behaviour for the response shape. To exercise access-token refresh locally, set ACCESS_TOKEN_TTL_SECONDS to a whole number from 60 to 3600. The default is 3600; the Terraform development configuration uses 900 (15 minutes). See User access token lifetime. stralos-api-documents also needs LocalStack and a worker:

​
Assistant service setup

stralos-api-assistant requires Node.js 24.19.0 (pinned in .node-version) and pnpm@11.10.0. The Assistant API Lambda uses the nodejs24.x managed runtime.
The service is a member of the root stralos pnpm workspace. Start it from the suite root with stralos-local (./stralos-local/stralos-local up assistant) alongside the rest of the stack. .env.example ships with AI_PROVIDER=google and GOOGLE_MODEL_ID=gemini-3.6-flash. The workspace’s scripts/setup-local-env.sh fills GOOGLE_API_KEY from dev SSM (requires your stralos-dev AWS login). Without dev access, paste in a personal Gemini API key. Set AI_PROVIDER=fixture to run without any live model provider. See AI copilot assistant service for the full configuration reference.

​
Frontend commands

Frontend packages generally expose:
API packages generally use pnpm build for TypeScript checking rather than a separate type-check script.

​
Shell API configuration

The shell’s local API defaults work without copying .env.example. Override a variable only when a service runs somewhere other than its normal local port. Production builds use the serving origin as the terminal fallback when no explicit build-time, runtime, or support override is present. Shell-specific variables and their local defaults: See Frontend architecture for the full precedence contract.

​
Admin console

stralos-admin-web is a pnpm workspace member. Its @stralos-co-nz/ui dependency resolves from a sibling stralos-ui checkout rather than the registry, so you must run pnpm install from the workspace root — not from inside stralos-admin-web — and build the sibling packages in order before starting the dev server. Prerequisites: stralos-admin-api running on port 3306 against the local stralos_admin database.
Run pnpm --dir stralos-ui build again after pulling stralos-ui — a stale dist folder looks clean to git status but renders components one release behind. The workspace root .npmrc points @stralos-co-nz at GitHub Packages for other private API packages. A read:packages token is required for a full workspace install:
To point the console at a different admin API, set VITE_ADMIN_API_URL in a local .env file (copy .env.example). The default is http://localhost:3306. Google sign-in also requires these four admin API settings in stralos-admin-api/.env:
Register http://localhost:5174/auth/callback as an authorised redirect URI on that Google OAuth client. When all four settings are absent, the API can start but the sign-in routes return 503. A partial configuration is invalid and stops the admin API during startup, so supply the complete set together. After pnpm admin:bootstrap on the admin API, sign in at http://localhost:5174 with the bootstrapped operator’s Google Workspace account. No password or TOTP enrolment is required; the first sign-in binds the Google account to the operator row.

​
Rates service API configuration

The Rates API calls Global (to validate supplier ownership), Estimate, and Activities (when resolving day-rate schedule line mappings). For each peer, set the direct URL variable (STRALOS_GLOBAL_URL, ESTIMATE_API_URL, ACTIVITIES_API_URL) or its *_SSM_PARAMETER companion naming the service-discovery parameter. stralos-local sets the direct URLs for you. There is no localhost fallback: when neither variable is set for a peer, the service refuses with a configuration error rather than calling a hard-coded port. See Deployment — Peer API URL resolution.

​
Activities feature API configuration

The Activities feature client uses three API services. Override their base URLs only when a service runs on a non-default port. See Frontend architecture for the full precedence contract.