Projects

A project is one GitHub repository connected to Nexos. Every branch you push to that repository becomes its own preview environment. Projects are where you configure how that happens: the Dockerfile, the services, the hooks, and the resource limits.

Creating a project

In the dashboard, click New Project and follow three prompts:

1. Pick a repository. Nexos lists the repos your GitHub account has access to. Selecting one installs a webhook for push and delete events.
2. Name the project. The slugified name shows up in every preview URL: {branch}-{project}.nexos.dev.
3. Choose defaults. Pick which services to provision (Postgres, Redis, S3) and set starting resource limits. All of this is editable later.

Build settings

Nexos builds your app with Docker and BuildKit. That means any stack that produces a container image works — Node, Go, Python, Rails, Rust, you name it.

• Dockerfile path — relative path to your Dockerfile. Default: Dockerfile.
• Build context — directory sent to BuildKit. Default: . (repo root).
• Build args — key-value pairs passed as --build-arg.

Companion services

Toggle these on and Nexos provisions them alongside your app. They're isolated per environment, so every branch gets its own clean copy.

• PostgreSQL 16 — connection string injected as DATABASE_URL.
• Redis 7 — connection string injected as REDIS_URL.

Your app just reads these environment variables at boot — no Nexos SDK required.

Lifecycle hooks

Hooks let you run a command inside the app container at a specific moment. Two are supported:

• on_deploy — runs after every deploy (brand new and incremental). Perfect for database migrations: npx prisma migrate deploy, rails db:migrate, etc.
• on_new — runs only on brand new deploys, after the seed is restored. Use it for one-time setup: create an admin account, generate an API key, call a third-party provisioning endpoint.

Resource limits

Each project can cap how much CPU and RAM its environments can use — both at runtime and during builds. Defaults come from your pricing tier; you can override per project:

• CPU limit — cores for the running app (e.g. 0.5, 1, 2, 4).
• Memory limit — RAM for the running app in MB.
• Build CPU / memory — resources during the image build phase.
• Build timeout — max build duration in seconds. Hung builds get killed.

Full breakdown in Resource Limits.

Configure in code with nexos.yaml

Rather than clicking through the dashboard you can commit a nexos.yaml file to the root of your repo. Nexos reads it on every push and applies the settings automatically before the build starts.

# nexos.yaml
name: my-app

build:
  dockerfile: ./Dockerfile
  context: .

app:
  port: 3000
  cpu: 1
  memory: 1024

services:
  postgres: true
  redis: true

hooks:
  on_deploy: npx prisma migrate deploy
  on_new: node scripts/seed-admin.js

env:
  NODE_ENV: production

nexos.yaml wins over the dashboard. If both are set, the file takes precedence. Fields omitted from the file keep their dashboard value, so the file can be a full spec or a partial override.

Full schema reference and AI-assisted authoring guide: nexos.yaml docs.