Getting Started

Skip the setup — install the Nexos MCP

Drop the Nexos MCP into Claude Code and the AI handles the whole flow for you — framework detection, Dockerfile, services, env vars, webhook walkthrough, deploy. From a Claude Code session in your repo:

claude mcp add nexos -- npx -y @nexos.rs/mcp
# then ask Claude:
> Set this repo up on Nexos.

Full instructions on the Claude Code MCP page. If you'd rather skip the MCP, the manual flow below still works — and the AI Agent Spec is a self-contained prompt you can paste into any AI assistant.

What you need

A GitHub repo you can deploy.
A Dockerfile at the repo root that listens on $PORT. If you don't have one, the AI prompt above will write a Dockerfile.nexos for you, or you can drop in this minimal Node example:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Step 1 — Sign in

Open https://app.nexos.rs and click Sign in with GitHub. Nexos requests read access to your repositories so it can install a webhook.

Step 2 — Create a project

Click New Project and pick a repo. Defaults are sensible — you can change them later, or commit a nexos.yaml to version-control the whole config.

Step 3 — Add secrets (if you have them)

Under Environment Variables, add any API keys or third-party credentials your app needs. Values are encrypted with AES-256-GCM. DATABASE_URL, REDIS_URL, and PORT are injected automatically — don't set them yourself.

Step 4 — Push a branch

git checkout -b try-nexos
git commit --allow-empty -m "first preview"
git push origin try-nexos

Nexos receives the webhook, builds your image, provisions the services you enabled, starts the containers, and wires up a preview URL. Watch logs stream live in the dashboard. Usually 30–60 seconds.

Step 5 — Open the URL

Find it on the environment page. It looks like try-nexos-my-app.nexos.rs. Paste it into a PR, Slack, or your browser.

Next pushes

The next push to the same branch is an incremental deploy: only your app container rebuilds. The database, cache, and other services persist — your test data and sessions survive. Use Reset Database on the environment page when you want a clean slate.

Where to go next

nexos.yaml — the single config file that controls your environment.
Deployments — what happens between push and live URL.
Environment Variables — secrets, auto-injected vars, bulk import.
Resource Limits — set CPU, RAM, build timeouts; check your quota.
API Reference — automate with an API key.

Running Nexos yourself

Nexos is open source. To self-host the control plane and run your own nodes, follow the README at nexos-dev/nexos. docker compose up -d brings up Postgres and Redis; then pnpm dev in apps/api and apps/web.