Atrium platform docs

Local development

Run local services and manage development sessions, environments, and database prerequisites.

Updated 2026-09-22

Start from a registered app

Install your service dependencies, sign in to the intended workspace, and run from the manifest root:

atrium validate
atrium dev

Use an online quickstart for a new app. Offline scaffolding alone does not register one. Session creation also does not publish a production deployment.

The CLI starts supported Next.js and FastAPI service commands. Check their terminal output and health routes before using the app. Local Hasura orchestration and public reverse tunnels are not released features of this workflow.

Choose services and session lifetime

atrium dev --service frontend
atrium dev --service frontend --service backend --ttl-seconds 3600
atrium dev status
atrium dev stop
atrium dev --fresh

These are separate operations; do not run them as an uninterrupted script.

Operation	Effect
`dev`	Starts local services using a development session; an eligible existing session can be reused.
`--service`	Selects manifest service keys. Repeat the flag for multiple services.
`--ttl-seconds`	Requests a lifetime from 300 to 86,400 seconds; default 28,800 seconds.
`dev status`	Inspects the current session without starting services or a heartbeat.
`dev stop`	Revokes the server session and forgets the local session reference.
`--fresh`	Replaces a prior session when you need a fresh environment.

Session reuse is tied to the app, developer, and checkout identity. A session is temporary, not a permanent environment. Use the status/expiry returned by the platform when diagnosing lost access.

Ctrl+C stops the local command; it is not a substitute for explicitly revoking server resources with dev stop. For custom clients, the session API supports creation, inspection, refresh through PATCH, and revocation through DELETE. Refresh extends the authorized session; it is not a production deployment.

Handle environment values safely

Starter .env.example files show configuration names, not usable credentials. The CLI obtains resolved development configuration for the requested services. Do not paste production database credentials into a development session, your manifest, or a browser-exposed variable.

atrium env <service> displays resolved service configuration and can contain secrets. It is not proof that a temporary isolated database was provisioned. Avoid publishing its output or blindly sourcing it into your shell. Keep generated/local environment files ignored and access-restricted.

The documented command surface is the published CLI 0.1.16 artifact. Newer local environment-file merging, startup/preflight fixes, and other locally patched behavior are not a release guarantee. Check atrium dev --help and release information before relying on additional behavior.

Isolated development databases

Managed isolated PostgreSQL development databases require Atrium to enable the development database capacity first. That setup is still required in the current environment; do not assume the Hasura profile will receive a working database automatically.

Where enabled, a session can receive an isolated development database with an empty starting schema. Apply your application's migrations and seed only appropriate test data. It is not a copy of production data, and it does not start a local Hasura server for you.

Inspect the database state in the session response. An unavailable or not-requested database is not ready for use. Stop the session if the app needs a database that was not provided, and confirm setup with Atrium. Explicit revocation requests cleanup; resource deletion is best-effort, and automatic cleanup of expired resources is not a guarantee.

Iterate and deploy deliberately

Edit and test locally, then run atrium validate and review the changes before atrium deploy. Deployment uploads a source snapshot; it does not depend on a public tunnel to your laptop. See Deployments for event streams and recent runtime logs.

For port conflicts, missing environment, or session failures, use Troubleshooting.