Environment reference
The studio reads two kinds of variable: NEXT_PUBLIC_* values, which are inlined at build time
and must be passed as Docker build arguments, and everything else, which is read when the server
starts. Spire reads its own set, prefixed SPIRE_, plus the shared sign-in secret.
The studio
Build time (NEXT_PUBLIC_*)
| Variable | Default | Purpose |
|---|---|---|
NEXT_PUBLIC_APP_SURFACE | studio in the image | studio serves unprefixed routes; any other value is the suite-embedded surface under /ade/studio |
NEXT_PUBLIC_STUDIO_BASE_PATH | unset | Explicit route prefix, overriding the surface's default |
NEXT_PUBLIC_MAIN_APP_URL | https://main.apiome.dev | The main app's origin. Sign-in redirects go to <main app>/login?callbackUrl=…. Must not be this deployment's own origin, or a signed-out visitor loops on /login |
NEXT_PUBLIC_STUDIO_URL | https://suite.apiome.dev | This deployment's own public URL; the main app links to it from the suite dropdown |
NEXT_PUBLIC_API_URL | https://api.apiome.dev | The public API origin |
NEXT_PUBLIC_REST_API_BASE_URL | http://localhost:8000/v1 | Build-time fallback for REST_API_BASE_URL |
NEXT_PUBLIC_SPIRE_API_BASE_URL | http://localhost:8099/v1 | Build-time fallback for SPIRE_API_BASE_URL |
NEXT_PUBLIC_STUDIO_UNIFIED_WORKSPACE | unset (off) | Workspace rollout stage: 1 (preview), default, only — see Deploy the studio |
NEXT_PUBLIC_STUDIO_WORKSPACE_PROFILER | unset | Shows the workspace's memory panel |
NEXT_PUBLIC_REPO_WORKFLOWS | unset | 1 shows the Arazzo Workflows node in the sidebar |
NEXT_PUBLIC_BROWSE_URL | unset | The browse app's URL, for links out of the studio |
Runtime
| Variable | Default | Purpose |
|---|---|---|
PORT | 3003 (image and run.sh; .env.example says 3004) | Listening port |
HOSTNAME (HOST as an alias) | 0.0.0.0 | Bind address |
REST_API_BASE_URL | the build-time fallback | apiome-rest's base URL, e.g. http://rest:8000/v1 in Docker |
SPIRE_API_BASE_URL | the build-time fallback | Spire's base URL, e.g. http://spire:8099/v1 in Docker |
DATABASE_URL | — | The Apiome Postgres database, for sessions and the Paths canvas's server actions. Same value as apiome-ui |
BETTER_AUTH_SECRET | — | The shared sign-in secret. Byte-identical to apiome-ui's. Without it no session can be read and no service bearer is minted |
BETTER_AUTH_URL | — | This deployment's own public URL (per origin) |
BETTER_AUTH_COOKIE_DOMAIN | inferred from the URLs | The parent domain both origins sit under, e.g. .apiome.dev. Identical to apiome-ui's. Used in production only |
INTERNAL_SERVICE_TOKEN | unset | Lets the studio's sign-in handler read admin-screen provider configuration from apiome-rest. Identical to apiome-ui's and apiome-rest's. Unset, same-origin sign-in uses the OAuth variables below only |
GITHUB_ID, GITHUB_SECRET, GITLAB_CLIENT_ID, GITLAB_CLIENT_SECRET | unset | OAuth providers for same-origin sign-in; the same values as apiome-ui |
STUDIO_BFF_FALLBACK_URL, APIOME_UI_INTERNAL_URL | unset | Development only: forward unported /api/* routes to a running apiome-ui. Omit in production |
OLLAMA_BASE_URL | http://localhost:11434 | The Ollama server behind the canvas AI buttons and chat |
OLLAMA_CHAT_CACHE_MAX_ENTRIES, OLLAMA_CHAT_CACHE_MAX_RESPONSE_CHARS, OLLAMA_CHAT_CACHE_DISABLED, OLLAMA_CHAT_CACHE_SEMANTIC_DISABLED, OLLAMA_CHAT_CACHE_SEMANTIC_THRESHOLD | — | The chat response cache's size, limits and semantic matching |
NEXTAUTH_URL, NEXTAUTH_COOKIE_DOMAIN, NEXTAUTH_SECRET | — | Retired. The studio reads none of them; setting one earns a startup warning |
Spire
Spire reads .env in its working directory and the process environment.
| Variable | Default | Purpose |
|---|---|---|
SPIRE_DATABASE_URL | — | The Apiome Postgres database. Spire's tables live in its authoring schema (search_path=authoring,public). Required for migrations, entitlement lookups and every store |
BETTER_AUTH_SECRET | insecure fallback outside production | The shared HS256 secret the studio signs service bearers with. Byte-identical to the studio's |
JWT_SECRET | insecure fallback outside production | A second secret to verify bearers against, for rotations |
NEXTAUTH_SECRET | — | Must be absent. Spire refuses to start while it is set, even blank |
SPIRE_CREDENTIAL_ENCRYPTION_KEY | — | Passphrase from which the key that encrypts stored tenant LLM API keys is derived |
SPIRE_AUTHORING_GATING_ENABLED | true | false skips the authoring entitlement check; authentication is still required |
SPIRE_SLATE_ARTIFACT_DIR | a temporary directory | Where Slate build ZIPs are written |
APP_ENV / SPIRE_ENVIRONMENT | — | production or prod makes Spire fail closed when a secret is missing instead of using a fallback |
FLYWAY_SCHEMA_HISTORY_TABLE, FLYWAY_DEFAULT_SCHEMA | flyway_schema_history, public | Overrides for the migration runner |
The ports: the studio listens on 3003, Spire on 8099, apiome-rest on 8000.