nexos.yaml

nexos.yaml is how you describe a project as code. Paste it into the dashboard's YAML editor, or commit it to the root of your repo and Nexos will pick it up on every push. It was designed to be AI-friendly: point your assistant at a repo, ask it to generate a nexos.yaml, and import the result.

Two ways to use it

1. Paste in the dashboard

Open Project → Settings and click the YAML toggle in the top right. The editor loads your current project as YAML; edit it and hit Apply YAML. Partial pastes work — e.g. drop in just an env: block to bulk-upsert variables without touching anything else.

2. Commit nexos.yaml to the repo

Save the file as nexos.yaml at the repo root and push. On every push Nexos fetches the file from the pushed commit and applies it to the project before the build starts. A branch can change its own config by editing the file in that branch.

Note: the file is fetched from GitHub's public raw endpoint. For now, public repos work out of the box; private-repo fetch requires a GitHub App installation token and is on the roadmap.

Full example

# nexos.yaml — full example with every field
name: my-app

build:
  dockerfile: ./Dockerfile
  context: .

app:
  port: 3000
  cpu: 1
  memory: 512

buildResources:
  cpu: 2
  memory: 2048
  timeout: 600

services:
  postgres:
    enabled: true
    version: "16"
    storageMb: 5120
  redis:
    enabled: true
    version: "7"

hooks:
  on_deploy: npm run db:migrate
  on_new: npm run db:seed

env:
  NODE_ENV: production
  LOG_LEVEL: info

containers:
  - name: api
    dockerfile: ./api/Dockerfile
    context: .
    port: 3001
    cpu: 1
    memory: 512
    public: true
    env:
      INTERNAL_TOKEN: super-secret

  - name: worker
    dockerfile: ./worker/Dockerfile
    context: .
    public: false

Minimal override

Every field is optional. You can commit a file with just the handful of settings you want to pin:

# nexos.yaml — minimal override
app:
  port: 8080
  memory: 1024

env:
  FEATURE_FLAG_X: "true"

Schema reference

Top-level fields

• name — project display name.
• build — Dockerfile + build context for the main app.
• app — port, CPU, memory for the running app container.
• buildResources — CPU, memory, and timeout during image build.
• services — toggle managed Postgres and Redis side-cars.
• hooks — commands that run at deploy time.
• env — shared env vars (injected into every container and passed as build-args).
• containers — multi-service setup: define extra containers that deploy alongside the main app.

build

• dockerfile — path to the Dockerfile. Default ./Dockerfile.
• context — build context dir. Default ..

app

• port — port the app listens on (exposed as PORT).
• cpu — CPU cores (e.g. 0.5, 1, 2).
• memory — RAM in MB.

buildResources

• cpu — cores available during build.
• memory — RAM available during build, in MB.
• timeout — max build duration in seconds.

services

Both postgres and redis accept either a boolean shorthand or an object:

services:
  postgres: true
  redis: true

• postgres.enabled, postgres.version ("14" / "15" / "16"), postgres.storageMb.
• redis.enabled, redis.version ("6" / "7").

hooks

• on_deploy — runs on every deploy (brand new and incremental). Use for prisma migrate deploy, rails db:migrate, etc.
• on_new — runs only on brand new environments, after the seed is restored. Use for one-time admin account creation, API-key provisioning, etc.

env

Shared env vars. Keys/values are upserted (existing keys not listed in the file are left intact). Values are stored AES-256-GCM encrypted at rest. Service-level containers[].env wins on key conflict.

containers

Define multiple services (frontend, API, worker) that deploy together. Nexos reconciles the list by name: declared containers are upserted, undeclared ones are removed. Each container takes the same fields as app, plus:

• name — lowercase alphanumeric + hyphens.
• public — if true, the container gets its own preview URL subdomain.
• env — per-container overrides, merged on top of the top-level env block.

AI workflow

Hand your repo to Claude, Cursor, or any agent and ask for a nexos.yaml:

"Look at this repo and generate a nexos.yaml that reflects its Dockerfile, exposed port, required services (Postgres, Redis), and any env vars referenced in code. Keep fields partial — skip anything you're not sure about."

The agent returns a YAML blob. Paste it into the dashboard's YAML editor and hit Apply YAML, or commit it to the repo and push — either way you land on a configured project without clicking through the form.

How it resolves against dashboard settings

The ordering is simple:

1. Project defaults populate every field.
2. Dashboard edits and pasted-YAML "Apply" actions overwrite those fields.
3. When a push arrives, if the commit contains a nexos.yaml, its fields overwrite the dashboard values before the build starts.

That means nexos.yaml in the repo always wins for fields it sets. Fields it omits stay at whatever the dashboard last set. Think of the repo file as the source of truth for anything you want version-controlled and the dashboard as the fallback for everything else.

Errors and safety

• Syntax errors or schema violations in a committed file are logged and skipped — the last good config applies and the deploy still runs. Check the deployment logs to see why your file was rejected.
• The dashboard editor surfaces parse errors inline before applying, so paste-and-apply is non-destructive if the YAML is broken.
• Secrets in env: are encrypted at rest with AES-256-GCM. Still — prefer GitHub Secrets / branch protections for anything sensitive committed to a repo.