apps.yml reference

apps.yml tells a sandbox how to run your product: the toolchain, the backing services, and each app’s setup, startup, routing, and health checks.

The project Configure page stores the shared baseline for each repository. Changes made by an agent inside a thread are saved as workspace-only overrides, so an app can be configured and tested alongside branch-only code without changing other threads. Promote the reviewed document in project settings when the code is available project-wide. 

tools:
  - nodejs_22
  - pnpm@10.32.1

env:
  NODE_ENV: development

setup:
  - pnpm install
  - pnpm db:migrate

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    connectionEnv:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 5

apps:
  web:
    dir_path: apps/web
    when:
      exists: apps/web/package.json
    port: 3000
    hmr_port: 30003
    routes:
      - path: /
    startup: pnpm dev --host 0.0.0.0
    health:
      - endpoint: /

  api:
    dir_path: apps/api
    port: 4000
    routes:
      - path: /api
    startup: pnpm start
    health:
      - endpoint: /healthz
tools
list of strings

Toolchain packages, as name or name@version — e.g. nodejs_22, pnpm@10.32.1, postgresql_16.

env
map

Repo-level environment variables injected into all apps and services.

setup
string or list

Repo-level shell commands run once when the workspace is built, before per-app setup — installs, migrations, seeds.

onepassword
object

Bind a 1Password item as the source of repo-level secrets: source_type (note or fields) plus source_item_id.

services
map

Named backing services (Postgres, Redis, …) run as containers next to your apps.

apps
map

Named applications — the processes Gentlybot starts, routes, and health-checks.

startup
string or listrequired

Command(s) that launch the app. The only required app field.

port
integer

HTTP port the app listens on. Required for endpoint health checks and URL routing.

hmr_port
integer

Separate HMR/WebSocket port (e.g. Vite). Upgrade requests are routed here instead of port.

dir_path
string

Subdirectory of the repo the app lives in (monorepos). Defaults to the repo root.

when.exists
string

Optional repo-relative sentinel. The app is skipped in workspaces where this path does not exist.

routes
list

How the app is exposed on the sandbox URL: each entry is exactly one of path (/api), prefix (a subdomain label), or subdomain.

env
map

App-level environment variables; override repo-level values.

setup
string or list

App-specific setup commands, run after repo-level setup.

health
list

Readiness checks — all must pass before the app counts as running. Each is one of endpoint: /path (2xx/3xx on port) or exists: relative/file.

onepassword
object

App-level 1Password binding, same shape as the repo-level one.

image
stringrequired

Container image, e.g. postgres:16 or redis:7.4.

environment
map

Environment variables for the service container.

ports
string or list

Port mappings, e.g. "5432:5432".

connectionEnv
map

Connection strings exported to your apps’ environment, e.g. DB_URL.

healthcheck
object

Container health probe: test (command array) plus optional interval, timeout, start_period, retries.

options
object

Runtime tuning: memory, cpus, shmSize, ulimits, capAdd, privileged.

Secrets

Don’t put real secrets in apps.yml. Bind a 1Password item with the onepassword field (repo-level or per-app) and Gentlybot resolves it into the sandbox environment at run time — secrets never need to be committed or stored in Gentlybot.