Atrium platform docs

Manifest schema

Configure services, access, and billing while keeping credentials and resolved state out of source.

Updated 2026-09-22

A service manifest

Keep atrium.yaml at the project root. This example defines a frontend, FastAPI backend, and Hasura service; choose only the services your app needs.

apiVersion: atrium.dev/v1
kind: Agent

metadata:
  name: my-agent
  displayName: My Agent
  description: A sample workspace app
  owner: dev@example.com

services:
  frontend:
    type: nextjs
    path: frontend
    buildCommand: bun run build
    dockerfile: frontend/Dockerfile
    healthCheck: /api/health
    domain: my-agent.atrium.st
  backend:
    type: python-fastapi
    path: backend
    dockerfile: backend/Dockerfile
    healthCheck: /health
  gql:
    type: hasura
    path: hasura
    healthCheck: /healthz

access:
  default: subscription
  public:
    - service: frontend
      paths: ["/", "/_next/**", "/favicon.ico", "/api/health"]
      methods: [GET, HEAD]
    - service: backend
      paths: ["/health"]
      methods: [GET, HEAD]

hosting:
  embedded: false

The access policy requires enrollment for routes not listed as public. Add an explicit Free or paid offering from Plans and entitlements before expecting customer enrollment. Configure Hasura prerequisites before deploying the database service.

Required fields

Field	Requirement
`apiVersion`	`atrium.dev/v1`
`kind`	`Agent`
`metadata.name`	Lowercase app slug.
`metadata.displayName`	Non-empty display name.
`services.*.type`	`nextjs`, `python-fastapi`, or `hasura`.
`services.*.path`	Non-empty path relative to the manifest root.

Service keys such as frontend and gql are identifiers used in commands, policy rules, and service URLs. The key is independent of the service type. Use the scaffold for a consistent starting layout.

Optional configuration

Field	Purpose
`metadata.description`, `metadata.icon`, `metadata.owner`	Summary, icon, and owner information.
`services.*.buildCommand`	Application build command.
`services.*.dockerfile`	Dockerfile path.
`services.*.healthCheck`	Health endpoint used to check the service.
`services.*.domain`	Requested visitor-facing domain; approval and DNS/TLS setup are separate.
`services.*.cloudRun.minInstances`	Requested minimum instance count, subject to platform limits.
`services.*.cloudRun.maxInstances`	Requested maximum instance count, subject to platform limits.
`services.*.env.build`	Allowlisted build-time values.
`hosting.embedded`	Whether the app requests embedded hosting; approval may be required.
`ci.triggerPaths`	Paths considered by configured repository deployment integration.
`ci.deploy`	Branch-to-environment mapping for that integration.
`access`	Route access levels and default policy.
`billing`	Offerings, prices, and entitlements.

A ci declaration does not install a repository integration. A domain declaration does not provision DNS or a certificate. Check integration setup and returned service URLs before relying on either.

Build environment and reserved values

The public manifest schema endpoint reports supported service types, reserved fields, and buildEnvAllowlist. Use it as the current source of validation rules. The allowlist currently contains NEXT_PUBLIC_FEATURE_X.

Build-time public values can be included in browser bundles. Never place credentials in a NEXT_PUBLIC_* variable or assume an arbitrary build variable is accepted.

Reserved root fields include status, resolved, and ui. Resolved service identity and region are also platform-managed. Do not set services.*.cloudRun.service or services.*.cloudRun.region.

Reserved environment values include ATRIUM_API_BASE_URL, NEXT_PUBLIC_API_BASE_URL, DATABASE_URL, HASURA_GRAPHQL_DATABASE_URL, NEON_DATABASE_URL, POSTGRES_PRISMA_URL, and POSTGRES_URL. Obtain runtime values through the supported environment/session workflow, not source-controlled manifest overrides.

Validate and apply changes

atrium validate
atrium deploy

Local validation catches manifest errors before deployment. Server validation remains authoritative; a locally accepted document can still fail policy, billing, or deployment prerequisite checks. Review the deploy preview before confirming.

Use atrium rename new-slug for a slug change rather than editing metadata.name on an existing app. Renaming can affect public URLs and integrations.

Continue with access rules, billing, and Manifest lifecycle.