Atrium platform docs

Manifest schema

Every supported atrium.yaml field, plus the fields Atrium owns and rejects from developer manifests.

Updated 2026-08-30

Full shape

apiVersion: atrium.dev/v1
kind: Agent

metadata:
  name: otto
  displayName: Otto
  description: Resume tailoring and job-application agent
  icon: ./icon.svg
  owner: dev@example.com

services:
  frontend:
    type: nextjs
    path: frontend
    buildCommand: bun run build
    dockerfile: frontend/Dockerfile
    cloudRun:
      minInstances: 0
      maxInstances: 10
    env:
      build:
        NEXT_PUBLIC_FEATURE_X: "true"
    healthCheck: /api/health

  backend:
    type: python-fastapi
    path: backend
    dockerfile: backend/Dockerfile
    cloudRun:
      minInstances: 0
      maxInstances: 5
    healthCheck: /health

  database:
    type: hasura
    path: hasura

hosting:
  embedded: false

ci:
  triggerPaths:
    - frontend/**
    - backend/**
    - hasura/**
    - atrium.yaml
  deploy:
    main: production
    deploy/*: staging

Any service can be omitted. A frontend-only agent, a backend-only agent, and an agent with a Hasura service are all valid as long as every declared service passes validation.

Required fields

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

Developer-owned fields

These fields can appear in atrium.yaml and can be changed through a normal commit or pull request.

Field	Notes
`metadata.displayName`	Human-facing name in marketplace surfaces.
`metadata.description`	Short summary for the agent.
`metadata.icon`	Relative path or URL for the agent icon.
`metadata.owner`	Owner contact or team identifier.
`services.*.path`	Service source root.
`services.*.buildCommand`	Build command for services that need one.
`services.*.dockerfile`	Dockerfile path if the service builds from Docker.
`services.*.cloudRun.minInstances`	Requested minimum, capped by plan.
`services.*.cloudRun.maxInstances`	Requested maximum, capped by plan.
`services..env.build.`	Build env keys from the platform allowlist only.
`services.*.healthCheck`	Health endpoint for service checks.
`hosting.embedded`	If true, the agent needs marketplace review before embedded listing.
`ci.triggerPaths`	Paths that should trigger builds.
`ci.deploy`	Branch-to-environment deploy mapping.

Build env allowlist

Build-time environment is intentionally narrow because Next.js NEXT_PUBLIC_* values are compiled into browser bundles.

The current CLI has a placeholder allowlist containing:

NEXT_PUBLIC_FEATURE_X

The authoritative allowlist should come from the platform. Until that endpoint is finalized, treat any other build env key as likely to fail validation.

Platform-owned fields

These fields never belong in the developer manifest.

Field	Why Atrium owns it
`status`	Resolved runtime state, not desired state.
`resolved`	Control-plane projection of the manifest plus injected values.
`ui`	Design system version is pinned by the scaffold and platform tooling.
`services.*.cloudRun.service`	Derived from agent identity.
`services.*.cloudRun.region`	Platform deployment policy.
`NEXT_PUBLIC_API_BASE_URL`	One platform endpoint contract for all agents.
`DATABASE_URL`	Provisioned credential, never source-controlled desired state.
`NEON_DATABASE_URL`	Provisioned database credential.
`HASURA_GRAPHQL_DATABASE_URL`	Provisioned Hasura backing database credential.

Validation rejects these fields as errors. It does not silently override them.

Slug changes

metadata.name is the slug, but changing it is not a normal manifest edit. Use:

atrium rename new-slug

The backend expects a payload with new_slug and confirm, where confirm exactly matches the new slug. This separate flow exists because a slug change can break live URLs and Cloud Run service identity.