Projects

A project is one GitHub repository connected to Nexos. Every branch you push becomes its own preview environment. Configure the project once; every branch inherits it.

Creating a project

1. Pick a repository. Selecting it installs a webhook for push, pull_request, and delete events. Preview environments spin up when a PR opens; pushes after that redeploy onto the existing environment.
2. Name it. The slug appears in every preview URL: {branch}-{project}.nexos.rs.
3. Pick services and starting limits. All editable later, or version-controlled via nexos.yaml.

Configure it once with nexos.yaml

The fastest way to set up a project is to commit a nexos.yaml at the repo root. It captures the Dockerfile, port, services, migrations, and env vars in one file. Nexos picks it up on every push.

# nexos.yaml
name: my-app

build:
  dockerfile: ./Dockerfile

app:
  port: 3000

services:
  postgres: true
  redis: true

hooks:
  on_deploy: npx prisma migrate deploy

Don't want to write it by hand? Point your AI assistant at the AI Agent Spec and it will generate the file (and a Dockerfile.nexos, if needed) for your repo.

What the dashboard controls

Everything in nexos.yaml, plus:

• Secrets. API keys, OAuth credentials, anything you don't want in git. Encrypted with AES-256-GCM. See Environment Variables.
• Team / billing. Move a project between personal and team ownership; pick which credit balance pays for it.
• Node pool selection. Shared (the global pool, the default) or private (only your own / your team's nodes).

If both a committed nexos.yaml and dashboard settings exist, the file wins for fields it sets. Fields it omits keep their dashboard value.

GitHub authentication (private repos)

Build nodes clone your repo over HTTPS. Public repos need no credentials; private repos need one of:

• GitHub OAuth. Click Authenticate with GitHub in project settings. Nexos stores your OAuth token AES-256-GCM encrypted and reuses it for every clone. One click covers every project on the same GitHub account.
• Personal Access Token (PAT). Paste a token into Settings → GitHub Authentication → Personal Access Token. Use this when OAuth isn't an option — most commonly when your GitHub account is already linked to a different Nexos user (the OAuth flow rejects a second link). Generate one at github.com/settings/tokens with the repo scope, or a fine-grained token with Contents: Read on the specific repository.

When both are configured for a project, the PAT takes precedence. PATs are scoped to the project they're saved on and stored AES-256-GCM encrypted; the dashboard only ever shows a Stored badge — the token itself never leaves the server after you save it.

Lifecycle hooks

Two hooks run inside the app container at deploy time:

• on_deploy — runs on every deploy. Database migrations live here.
• on_new — runs only the first time an environment is created. One-time setup (admin user, API key provisioning).

Resource limits

Each project can cap CPU and RAM for its containers — both runtime and build-time. Defaults come from your plan; override per project in the dashboard or in nexos.yaml. Full breakdown: Resource Limits.