aria.yaml reference: every field

aria.yaml is the one file that tells Aria what your app needs to run: its services, its databases, and which variable goes to which service. Put it at the root of your repository (or tell Aria where it is). Aria AI or your coding agent usually writes it, Aria checks it with line numbers, and Aria applies it on the first launch and on every push. Unknown keys are refused, so a typo is caught before anything is deployed.

What does a whole file look like?

version: 1
name: my-app
services:
  web:
    type: web
    path: apps/web
    port: 3000
    healthcheck: /
    domain: "@"
databases:
  main:
    type: postgres
    migrations: db/migrations
env:
  DATABASE_URL:
    services: [web]
    from: main.url
resources:
  users: 200

Only version and services are required.

What are the top-level fields?

Names of services, databases, volumes and registries use lowercase letters, digits and dashes, start with a letter, and have at most 31 characters. A service cannot be called supabase, inbox or email, or end in -supabase. A database cannot share a service’s name. The file is up to 64 KB.

What can a service say?

services.<name> describes one thing that runs.

A static site cannot use image, volumes, gpu, stop_grace_period, shm_size, realtime or migrate. A worker cannot be public or have a domain.

What can a database say?

databases.<name> adds one database. Aria runs Postgres, Redis and Supabase.

More on each kind is on Databases and Self-hosted Supabase.

What can a variable say?

env.<NAME> decides which services get a variable and where its value comes from. A variable reaches only the services it lists. With no services it reaches every service, so always give a secret a services list.

Use only one of from, template, generate and value per variable. Everything built into a browser bundle is public: never wire a credential into a variable with a browser prefix. The full story is on Environment variables.

How does one service or database reference another?

from: name.attribute and ${name.attribute} read a value Aria knows. name is a key under databases or services, or the word email. Aria works out every address before it builds anything.

public_host is the public address without https://, handy for building a wss:// URL in a template. url and public_host need a public service. From another service, read internal_url. Aria orders services by what they read, so a frontend that reads an API’s address waits for the API.

What can the backup block say?

Without a backup block, Aria already backs up your databases and volumes every night. Add one to choose the schedule and what is kept. See Backups.

What are registries and resources?

registries.<name> logs in to a private registry so Aria can pull an image. It takes host (like ghcr.io), username, and password_secret, the name of a secret you enter in Aria. That secret is used only to pull images, never given to a service, and cannot also appear under env.

resources gives Aria hints:

What are the limits?

• Up to 12 services, 6 databases and 200 variables per project, and up to 5 projects on one server by default. Every limit is on Limits.
• Databases are Postgres (16 or 17), Redis (7) and Supabase. There is no MySQL or MongoDB.
• Up to 8 volumes per service.
• Commands are one line, with no backticks, single quotes or $( ).
• Supabase needs about 4 GB of memory on its own.

Example 1: three services, Postgres and Redis

This stack has a web front end built from a Dockerfile at the repository root, an API built from its folder that runs its own migrations, and a worker that waits for a key only you can give.

version: 1
name: stack-demo
services:
  web:
    type: web
    path: apps/web
    context: .
    dockerfile: apps/web/Dockerfile
    port: 3000
    healthcheck: /
  api:
    type: api
    path: apps/api
    start: node server.js
    migrate: node migrate.js
    port: 8080
    healthcheck: /health
  worker:
    type: worker
    path: apps/worker
    context: .
    dockerfile: apps/worker/Dockerfile
databases:
  main:
    type: postgres
    migrations: db/migrations
    seed: db/seed.sql
  cache:
    type: redis
email:
  enabled: true
  from: hello@example.com
env:
  PUBLIC_SITE_NAME:
    services: [web]
    value: Stack demo
    build: true
  API_URL:
    services: [web]
    from: api.internal_url
  DATABASE_URL:
    services: [api]
    from: main.url
  REDIS_URL:
    services: [api, worker]
    from: cache.url
  SESSION_SECRET:
    services: [api]
    generate: secret
  SMTP_URL:
    services: [api]
    from: email.smtp_url
  MAIL_FROM:
    services: [api]
    from: email.from
  EXTERNAL_API_KEY:
    services: [worker]
    required: true
    secret: true
    description: Any value. The worker refuses to start without it.

What to notice:

• web reads the API through api.internal_url, so it starts after the API.
• api runs node migrate.js before each new version takes traffic.
• The database schema comes from db/migrations, applied in order, each once, and db/seed.sql runs once on a new database.
• EXTERNAL_API_KEY is required and secret, so the worker waits until you enter it with aria env add EXTERNAL_API_KEY.
• PUBLIC_SITE_NAME is build: true because the web build reads it.

Example 2: a web app on self-hosted Supabase

One web service on Supabase. The app receives Supabase’s address and keys through variables, and one extra variable reaches an edge function.

version: 1
name: supabase-demo
services:
  web:
    type: web
    path: .
    dockerfile: Dockerfile
    port: 3000
    healthcheck: /
databases:
  main:
    type: supabase
env:
  NEXT_PUBLIC_SUPABASE_URL:
    services: [web]
    from: main.url
    build: true
  NEXT_PUBLIC_SUPABASE_ANON_KEY:
    services: [web]
    from: main.anon_key
    build: true
  SUPABASE_INTERNAL_URL:
    services: [web]
    from: main.internal_url
  SUPABASE_SERVICE_ROLE_KEY:
    services: [web]
    from: main.service_role_key
  DATABASE_URL:
    services: [web]
    from: main.db_url
  DEMO_FUNCTION_SECRET:
    services: [main]
    generate: secret
  GITHUB_SECRET:
    services: [main]
    required: true
    secret: true
    description: The GitHub OAuth app's client secret, for signing in with GitHub.

What to notice:

• The two NEXT_PUBLIC_ variables are public by design, so they are marked build: true and are safe in a browser bundle. The service-role key is not, and goes only to server code.
• services: [main] names the Supabase database, not a service. That delivers the variable to the database’s edge functions and to the config.toml that Supabase reads. GITHUB_SECRET turns on GitHub sign-in once it has a value.
• Supabase’s own folder (supabase/ with migrations/, seed.sql, functions/ and config.toml) lives in the repository. Aria applies it on every launch and push.

How do I check the file?

Your coding agent can call the validate_stack_file tool, which returns problems with line numbers and warnings about things that are allowed but probably not what you meant. In the browser, Aria checks the file as you paste it. Problems stop a file from being saved. Warnings never block anything. Aria AI runs the same check as it writes the file. See Aria AI and Connect a coding agent.