DEV Community: Saif Ali

NEXUS AI - Claude Code Tutorial

Saif Ali — Sun, 09 Aug 2026 13:30:56 +0000

Most Claude Code tutorials stop at "here's how to install it." That's like teaching someone to drive by showing them the ignition. This Claude Code tutorial goes further — you'll use it to build a real AI-powered app from scratch and deploy it to production, step by step.

By the end you'll have a working document Q&A API and a live deployment URL. The whole thing takes about an afternoon.

What Claude Code actually is (and why it's different)

Claude Code is Anthropic's AI coding agent that runs in your terminal. Unlike copilot-style tools that suggest individual lines inside an editor, Claude Code operates at the project level — it reads your entire codebase, understands how files relate to each other, and makes multi-file changes with full context.

The practical difference: you describe what you want to build, and Claude Code writes the code, runs commands, fixes errors, and iterates — without you switching between a chat window and your editor. It's AI-augmented development where the AI is a collaborator in your actual workflow, not a suggestion box beside it.

What makes it powerful for AI app development specifically:

It can generate boilerplate for FastAPI, Express, or any framework in seconds
It writes tests alongside the code it generates
It catches its own mistakes by running the code and reading error output
It handles the tedious parts (CI config, requirements.txt, test scaffolding) while you focus on the actual problem

Getting started: install and configure Claude Code

Install

npm install -g @anthropic-ai/claude-code

Requires Node.js 18+. Verify:

claude --version

Authenticate

claude

On first run, Claude Code opens a browser window to authenticate with your Anthropic account. Once authenticated, it drops you into an interactive session in your current directory.

Your first command

Navigate to an empty project folder and try:

mkdir my-ai-app && cd my-ai-app
claude

In the Claude Code prompt:

> Scaffold a FastAPI project with a single /health endpoint, a requirements.txt, and a .gitignore

Claude Code will create the files, show you what it's doing, and confirm. This is the core interaction pattern: describe the outcome, let it execute.

Build a real AI app with Claude Code

We're building a document Q&A API — you upload a text document, ask questions about it, and get answers grounded in the document's content. It's a practical RAG (retrieval-augmented generation) pattern used in real products.

Step 1 — Scaffold the project

In your Claude Code session:

> Create a FastAPI app for document Q&A. The app should:
> - Accept a POST /upload endpoint that takes a text file and stores it in memory
> - Accept a POST /ask endpoint that takes a document_id and a question, then answers using OpenAI gpt-4o-mini
> - Return answers in JSON with the answer text and a confidence field
> - Include a requirements.txt with fastapi, uvicorn, openai, and python-multipart

Claude Code will generate the full project structure:

my-ai-app/
├── main.py
├── requirements.txt
├── .gitignore
└── README.md

It writes the entire main.py — endpoints, in-memory document store, OpenAI call — in one pass.

Step 2 — Run it and fix errors

> Run the app locally with uvicorn and show me any errors

Claude Code executes uvicorn main:app --reload, reads the output, and if there are import errors or missing packages it fixes them automatically. This loop — run, read error, fix — is where Claude Code earns its keep. You don't context-switch; it just handles it.

Step 3 — Add real retrieval (not just stuffing the whole document)

The naive version sends the entire document to the model on every question. That breaks on large files and wastes tokens. Ask Claude Code to improve it:

> The current /ask endpoint sends the full document to OpenAI on every request.
> Refactor it to:
> - Split documents into 500-token chunks on upload
> - Use cosine similarity on TF-IDF vectors to find the top 3 relevant chunks
> - Only send those 3 chunks to OpenAI as context
> - Use numpy and sklearn for the vector operations

This is multi-file, multi-concept work. Claude Code will update main.py, add sklearn and numpy to requirements.txt, and implement the chunking + retrieval logic coherently. It understands that changing the upload flow affects the query flow and handles both.

Step 4 — Write tests

> Write pytest tests for both endpoints. Include:
> - A test that uploads a sample document and verifies the document_id is returned
> - A test that uploads a document, then asks a question whose answer is clearly in the document
> - A test that asks about a document_id that doesn't exist and expects a 404
> Mock the OpenAI call so tests don't need a real API key

Claude Code generates test_main.py with the exact structure you described, uses pytest-mock for the OpenAI mock, and adds the test dependencies to requirements.txt.

Run them:

> Run the tests and fix any failures

Claude Code runs pytest, reads the output, and iterates until they pass. The critical detail: it doesn't just generate tests and hand them back — it runs them and closes the feedback loop.

The CLAUDE.md file: your project's AI instruction layer

One of the most underused Claude Code features is CLAUDE.md — a file in your project root that Claude Code reads at the start of every session. Think of it as a permanent briefing document for your AI collaborator.

Create one:

> Create a CLAUDE.md for this project that documents:
> - The tech stack (FastAPI, OpenAI, sklearn)
> - The coding conventions we used (snake_case, type hints everywhere, docstrings on public functions)
> - The test setup (pytest, mock OpenAI calls)
> - What the /upload and /ask endpoints do

From this point on, any new Claude Code session on this project starts with full context. You don't re-explain the stack every time.

A good CLAUDE.md includes:

# Project: Document Q&A API

## Stack
- FastAPI + Uvicorn (Python 3.11)
- OpenAI gpt-4o-mini for generation
- sklearn TF-IDF + cosine similarity for retrieval
- pytest + pytest-mock for testing

## Conventions
- Type hints on all function signatures
- Snake_case everywhere
- Docstrings on all public functions

## Architecture
- Documents stored in-memory (dict keyed by UUID)
- Chunks: 500 tokens, 50-token overlap
- Top 3 chunks retrieved per query

## Running locally
uvicorn main:app --reload --port 8000

## Running tests
pytest -v

Deploy to production with the NEXUS AI CLI

Your app is built and tested. Now get it live — no Dockerfile required.

NEXUS AI detects your framework, builds the container for you, and deploys it. You push source code; NEXUS AI handles everything from there.

Step 5 — Push source to GitHub

Initialize a repo and push:

git init
git add .
git commit -m "initial: document Q&A API"
gh repo create my-ai-app --public --source=. --push

Or push to an existing repo. The only requirement is that your requirements.txt is at the project root — NEXUS AI uses it to detect that this is a Python app.

Step 6 — Install the NEXUS AI CLI

# Linux
curl -fsSL https://nexusai.run/install.sh | bash

# macOS
curl -fsSL https://nexusai.run/install-mac.sh | bash

Verify:

nexus --version

Step 7 — Deploy from source

# Log in to NEXUS AI
nexus auth login

# Deploy directly from your GitHub repo — no Docker required
nexus deploy source \
  --repo https://github.com/your-org/my-ai-app \
  --name doc-qa-api \
  --port 8000 \
  --provider gcp_cloud_run

# Add the OpenAI key as an encrypted secret
nexus secret create OPENAI_API_KEY --deployment doc-qa-api

# Attach a custom domain
nexus domain add api.yourcompany.com --deployment doc-qa-api

NEXUS AI clones your repo, detects the Python/FastAPI framework, builds a production container image, and deploys it. Within 2–3 minutes you have a live URL with TLS and autoscaling. Stream logs to verify:

nexus deploy logs doc-qa-api --follow

Automate deploys with GitHub Actions

Ask Claude Code to write the CI/CD config:

> Write a GitHub Actions workflow that redeploys the NEXUS AI deployment on every push to main.
> Use NEXUSAI_TOKEN as a secret. The deployment name is doc-qa-api.

Claude Code generates a complete .github/workflows/deploy.yml. The workflow calls nexus deploy redeploy doc-qa-api — NEXUS AI pulls the latest source, rebuilds the container, and rolls it out. Every push to main goes to production automatically.

Advanced Claude Code patterns for AI development

Multi-file refactoring

Claude Code handles refactors that would take hours manually. Example:

> The document store is currently an in-memory dict. Refactor it to use Redis so documents
> persist across server restarts. Update all references, add redis to requirements.txt,
> and update the CLAUDE.md architecture section.

It updates main.py, requirements.txt, and CLAUDE.md in one coherent pass — and since NEXUS AI builds from source, you just push the changes and redeploy.

Debugging without context-switching

When something breaks in production:

nexus deploy logs doc-qa-api --tail 50

Copy the error, paste it into Claude Code:

> Getting this error in production logs: [paste error]
> Find the root cause and fix it.

Claude Code reads the relevant code, identifies the issue, and applies the fix — all without you manually tracing through stack traces.

Using Claude Code for code review

Before opening a PR:

> Review the changes in git diff HEAD~1 for:
> - Security issues (injection, hardcoded secrets, unsafe deserialization)
> - Missing input validation on the API endpoints
> - Performance issues in the chunking logic

Claude Code runs the diff and produces a structured review with specific line references.

Common Claude Code mistakes to avoid

Giving vague prompts. "Make this better" produces mediocre output. "Refactor the chunking function to reduce memory allocation by processing tokens in a streaming fashion instead of loading the full document" produces a specific, actionable change.

Not using CLAUDE.md. Without it, you re-explain your stack every session. Ten minutes setting it up saves hours over the life of a project.

Accepting the first output blindly. Claude Code is fast, not infallible. Run the tests after every significant change. When they fail, let Claude Code fix them — that feedback loop is what makes it reliable.

Letting it over-engineer. Claude Code will sometimes propose abstractions you don't need. If you asked for a simple endpoint and got a three-layer architecture with an abstract repository pattern, push back: "Simplify this — no abstraction layers, just the endpoint and direct database calls."

Not scoping the context. In very large codebases, claude in the root directory gives it the whole repo. For a focused change, navigate to the relevant subdirectory first. Smaller context = more precise output.

Frequently asked questions

Does Claude Code work with languages other than Python?

Yes. Claude Code works with any language — TypeScript, Go, Rust, Ruby, Java. The same patterns apply: scaffold with a prompt, run it, let Claude Code fix errors. The CLAUDE.md approach works especially well in polyglot repos where you need to document which parts use which language.

Is Claude Code safe to run on production codebases?

Claude Code asks for confirmation before writing files or running commands. You control what it executes. For sensitive production repos, review the proposed changes before confirming — Claude Code shows you a diff before applying it. Never give it credentials directly; use environment variables and secrets managers.

How is Claude Code different from GitHub Copilot?

Copilot autocompletes individual lines and functions inside an editor. Claude Code operates at the project level in the terminal — it understands the full codebase, can run code, read test output, and make coordinated multi-file changes. They're complementary: Copilot for keystroke-level suggestions, Claude Code for larger tasks.

Can I use Claude Code without an Anthropic account?

No. Claude Code requires an Anthropic API key or Claude.ai Pro/Max subscription. Usage via the API is billed based on token consumption. The claude.ai subscription tiers include a monthly usage allocation.

What's the best way to handle large codebases?

Use .claudeignore (same syntax as .gitignore) to exclude directories that aren't relevant to your current task — node_modules, dist, venv, build artifacts. This keeps Claude Code's context focused on what matters and reduces token usage.

What you built

Start to finish: a document Q&A API scaffolded by Claude Code, with chunked retrieval, pytest coverage, and a live deployment on NEXUS AI — all without writing a Dockerfile or touching a browser.

That's AI-augmented development in practice. Claude Code handled the scaffolding, boilerplate, tests, and debugging loop. You handled the architecture decisions and product requirements. The result ships faster and has better test coverage than the same work done manually.

The NEXUS AI CLI handles the deployment side of this workflow. Install it, run nexus auth login, and your next Claude Code-built app is one command away from production.

NEXUS AI Audit

Saif Ali — Sun, 09 Aug 2026 13:29:25 +0000

Audit logs and compliance: what gets recorded and why

Published: April 21, 2026

Category: Security · Compliance

Reading time: 15 minutes

Author: NEXUS AI Team

A production incident happens at 2:47 AM. You wake up to alerts. By the time you open your laptop, the question isn't "what failed" — your monitoring already told you that. The question is "who changed what, when, and from where?"

Without audit logs, that question takes hours. With audit logs, it takes minutes.

NEXUS AI records 42 distinct event types across 7 categories — every authentication attempt, every secret operation, every deployment action, every permission change. This post covers exactly what gets recorded, what each severity level means, how retention works, and how the audit log maps to the compliance controls your team, auditors, and regulators care about.

Why audit logs exist — and why most teams underinvest in them

Audit logs are not a debugging tool. They are an accountability system.

The difference matters. A debugging tool helps you understand why software broke. An accountability system answers a harder set of questions:

Did an authorized person take this action?
From a recognized location?
At a time that makes sense?
On the resource they were supposed to touch?

These are the questions a security incident forces you to answer — and the questions compliance auditors ask during a review. Every minute you spend reconstructing context from application logs and git history is a minute your accountability system didn't pay for itself.

NEXUS AI's audit log is designed to answer accountability questions in seconds, not hours.

The event catalog: 42 event types, 7 categories

Every event stored in the audit log has a named type. Here is the complete catalog.

Authentication events

Event	What triggered it	Default severity
`LOGIN_SUCCESS`	Successful sign-in via password or OAuth	INFO
`LOGIN_FAILED`	Failed sign-in attempt (wrong password, invalid token)	WARNING
`LOGOUT`	Explicit sign-out	INFO
`REGISTER`	New account created	INFO
`TOKEN_REFRESH`	Session token refreshed	INFO
`TOKEN_EXPIRED`	Session token expired and was rejected	WARNING

Authentication events are the first line of accountability. A single LOGIN_FAILED is noise. Fifteen LOGIN_FAILED events from the same IP in 90 seconds is a brute-force signal — recorded, flagged, and available for your SIEM in real time.

Deployment events

Event	What triggered it	Default severity
`DEPLOYMENT_CREATED`	New deployment provisioned	INFO
`DEPLOYMENT_UPDATED`	Deployment configuration changed	INFO
`DEPLOYMENT_STARTED`	Stopped deployment brought back online	INFO
`DEPLOYMENT_STOPPED`	Running deployment halted	INFO
`DEPLOYMENT_DELETED`	Deployment permanently removed	INFO
`DEPLOYMENT_FAILED`	Build or container start failed	ERROR
`DEPLOYMENT_SCALED`	Replica count changed	INFO

Every deploy action is tied to the actor who triggered it — a user email, a token ID, or both. When a deploy fires at 3 AM, you know whether it was a CI token, a scheduled job, or a human who shouldn't have been working at 3 AM.

Security events

Event	What triggered it	Default severity
`DOCKERFILE_VALIDATION_FAILED`	Submitted Dockerfile failed safety checks	WARNING
`RATE_LIMIT_EXCEEDED`	API caller exceeded request rate limits	WARNING
`UNAUTHORIZED_ACCESS`	Request rejected due to insufficient permissions	WARNING
`SUSPICIOUS_ACTIVITY`	Behavioral anomaly detected by the security monitor	CRITICAL
`CONTAINER_ESCAPE_ATTEMPT`	Container process attempted to break isolation	CRITICAL

SUSPICIOUS_ACTIVITY and CONTAINER_ESCAPE_ATTEMPT are the two events that trigger an immediate alert. They are never demoted to WARNING or lower.

Resource events

Event	What triggered it	Default severity
`RESOURCE_LIMIT_EXCEEDED`	Deployment exceeded its CPU, memory, or storage limit	WARNING
`HIGH_CPU_USAGE`	Container CPU usage crossed threshold	WARNING
`HIGH_MEMORY_USAGE`	Container memory usage crossed threshold	WARNING

Resource events are included in the audit log — not just the metrics system — because they tell the story of capacity-related incidents. A deployment that gets quietly OOM-killed at 4 PM on a Tuesday has a paper trail.

Administrative events

Event	What triggered it	Default severity
`USER_CREATED`	New team member account created or invited	INFO
`USER_DELETED`	Team member removed from the organization	INFO
`PERMISSION_CHANGED`	Role or scope assignment changed	INFO
`CONFIG_CHANGED`	Organization-level configuration updated	INFO

Administrative events answer the access-review question: not just who has access now, but who granted it, when, and to whom. Every PERMISSION_CHANGED event records the before and after state in the details JSON field.

Project events

Event	What triggered it	Default severity
`PROJECT_CREATED`	New project created	INFO
`PROJECT_UPDATED`	Project metadata or settings changed	INFO
`PROJECT_DELETED`	Project and all its deployments deleted	INFO

Secret and vault events

Event	What triggered it	Default severity
`SECRET_CREATED`	New secret stored in the vault	INFO
`SECRET_UPDATED`	Secret value changed	INFO
`SECRET_ROTATED`	Secret rotated (new value, same name)	INFO
`SECRET_DELETED`	Secret removed from the vault	INFO
`SECRET_REVEALED`	Secret value decrypted for display	WARNING
`SECRET_LISTED`	Secret names listed (values not returned)	INFO
`SECRET_RUNTIME_ACCESSED`	Secret decrypted for container injection at deploy time	INFO

SECRET_REVEALED is marked WARNING by design. The vault never returns plaintext values through normal operations — if a SECRET_REVEALED event fires, an admin explicitly requested a value display. That is worth noting.

SECRET_RUNTIME_ACCESSED records every time a secret is decrypted for injection into a running container. On a high-frequency redeploy environment, this creates a complete timeline of which secrets were active in which container instances.

Database intelligence events

Event	What triggered it	Default severity
`DATABASE_ACCESSED`	External database connection established	INFO
`DATABASE_MODIFIED`	Schema change or DDL applied to external database	WARNING
`DATABASE_QUERY_EXECUTED`	SQL query executed against an external database source	INFO

DATABASE_MODIFIED is promoted to WARNING because schema changes are high-impact and difficult to reverse. Every DDL statement executed through NEXUS AI's Database Intelligence layer — whether applied directly or via a proposed fix — produces a record.

The audit log record

Every event writes a single record to the audit_logs table. Here is what that record looks like in full:

{
  "id": "f3c8a21b-4d9e-4a7f-b6c1-e2d8f0a3b591",
  "eventType": "DEPLOYMENT_CREATED",
  "severity": "INFO",
  "userId": "usr_01HX9...",
  "organizationId": "org_01HX9...",
  "ipAddress": "140.82.114.3",
  "userAgent": "nexusapp-cli/2.0.0 node/20.11.0",
  "resourceId": "dep_api-prod",
  "resourceType": "deployment",
  "action": "DEPLOYMENT_CREATED",
  "details": {
    "deploymentName": "api-prod",
    "image": "ghcr.io/org/api:sha-abc123",
    "region": "us-east-1",
    "provider": "AWS_APP_RUNNER",
    "tokenId": "tok_01HX9..."
  },
  "success": true,
  "errorMessage": null,
  "timestamp": "2026-04-21T09:17:05.000Z"
}

Every field is intentional:

Field	Why it exists
`id`	Unique record identifier — stable reference for incident tickets
`eventType`	Machine-readable event name — filterable, indexable, SIEM-parseable
`severity`	INFO / WARNING / ERROR / CRITICAL — drives alerting and dashboards
`userId`	The human actor (null if action was taken by a token with no session)
`organizationId`	Tenant boundary — logs are always org-scoped; cross-tenant reads are impossible
`ipAddress`	Source IP of the request — critical for geolocation anomaly detection
`userAgent`	CLI version, browser, SDK — surfaces automation vs. human access
`resourceId`	The specific resource acted upon — deployments, secrets, users
`resourceType`	The category of resource — enables filtering by type
`action`	Human-readable description of what happened
`details`	Freeform JSON — event-specific context (image tag, region, old role, new role)
`success`	Whether the action completed successfully
`errorMessage`	If `success` is false, why it failed
`timestamp`	UTC timestamp of the event — stored with millisecond precision

The details field is where event-specific context lives. A PERMISSION_CHANGED record includes the old role and new role. A SECRET_RUNTIME_ACCESSED record includes the deployment ID and the name (not value) of the secret. A LOGIN_FAILED record includes the email attempted.

Severity levels

NEXUS AI uses four severity levels. They control how an event is stored, surfaced, and retained.

INFO

Normal system operation. Every successful deploy, login, and secret list operation lands here. INFO events are written to the database and available for query, but they do not trigger any alert. They form the baseline — the record of what "normal" looks like.

WARNING

Something worth noting. Failed logins, rate limit hits, secret reveal operations, and Dockerfile validation failures are WARNING events. They do not indicate a breach, but they indicate conditions that — in volume or combination — warrant investigation. Five LOGIN_FAILED events is noise. Fifty in ten minutes is a pattern your SIEM should surface.

ERROR

An action failed in a way that requires attention. DEPLOYMENT_FAILED is an ERROR. These events are logged to the application error stream in addition to the database, so they appear in your observability pipeline immediately.

CRITICAL

Immediate action required. Only two event types default to CRITICAL: SUSPICIOUS_ACTIVITY and CONTAINER_ESCAPE_ATTEMPT. CRITICAL events trigger the alerting pipeline — currently logging to the critical error stream, with email, Slack, and PagerDuty integrations on the roadmap. CRITICAL events are also exempt from the standard 90-day retention purge. They are kept indefinitely, regardless of plan.

The security score

NEXUS AI's security monitor computes a rolling 100-point security score for each organization, recalculated across a configurable window (default: 7 days).

The score starts at 100 and deducts based on event volume:

Event category	Deduction per occurrence
Failed login (`LOGIN_FAILED`)	−2 points
Rate limit exceeded (`RATE_LIMIT_EXCEEDED`)	−1 point
Dockerfile validation failure (`DOCKERFILE_VALIDATION_FAILED`)	−5 points
Critical security event (`severity: CRITICAL`)	−10 points

A score of 100 means no adverse events in the review window. A score of 60 means something is worth investigating. A score below 40 should trigger an active security review.

The score is visible in the NEXUS AI dashboard under Settings → Security and is available via the API at GET /api/audit/security-summary.

Retention policy

Plan	Retention window	CRITICAL event retention
Starter	90 days	Indefinite
Pro	90 days	Indefinite
Enterprise	Configurable (env: `AUDIT_LOG_RETENTION_DAYS`)	Indefinite
Enterprise On-Prem	You own the database	You own the database

The retention job runs daily at 3:30 AM UTC. It purges records older than the retention window — except CRITICAL events, which are never automatically purged.

On Enterprise, set AUDIT_LOG_RETENTION_DAYS to any positive integer. Regulated industries typically set this to 365 (HIPAA minimum) or 2555 (7-year financial records requirement).

# Example: 365-day retention for HIPAA workloads
AUDIT_LOG_RETENTION_DAYS=365

On Enterprise On-Prem, you bring your own PostgreSQL cluster. Audit logs live in your database, under your retention and backup policies, with no data leaving your infrastructure.

Accessing your audit logs

Dashboard

The audit log viewer is at Settings → Audit Logs in the NEXUS AI dashboard. Filter by event type, severity, date range, and user. Paginated, searchable, exportable.

API

The audit log API is at /api/audit/logs:

# Get the last 50 logs
curl -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/logs?limit=50"

# Filter by event type
curl -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/logs?eventType=SECRET_UPDATED&limit=100"

# Filter by severity
curl -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/logs?severity=WARNING&limit=100"

# Date range (ISO 8601)
curl -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/logs?startDate=2026-04-01T00:00:00Z&endDate=2026-04-21T23:59:59Z"

# Security summary for the last 7 days
curl -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/security-summary?days=7"

CSV export

Export up to 10,000 log records as a CSV file — ready to upload to your SIEM, compliance platform, or auditor portal:

# Export last 30 days to CSV
curl -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/export?startDate=2026-03-21T00:00:00Z" \
  -o audit-logs-march-2026.csv

The CSV includes all fields: timestamp, event type, severity, user ID, IP address, action, success, error message, resource ID, and resource type. The details JSON field is serialized as a string in the CSV export.

Available filter endpoints

Endpoint	Purpose
`GET /api/audit/logs`	Query logs with filters
`GET /api/audit/export`	Download CSV (up to 10,000 records)
`GET /api/audit/security-summary`	7-day security summary and score
`GET /api/audit/security-metrics`	Real-time threat metrics
`GET /api/audit/event-types`	List all 42 event types and 4 severity levels
`GET /api/audit/user-activity/:userId`	30-day activity summary for a specific user

Audit logs in a real incident

Here is how audit logs actually look during an incident response workflow.

Scenario: At 11:42 PM, a production deployment stops unexpectedly. The on-call engineer opens the audit log.

Step 1: Filter for recent deployment events on the affected resource.

curl -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/logs?eventType=DEPLOYMENT_STOPPED&limit=10"

Result:

{
  "eventType": "DEPLOYMENT_STOPPED",
  "severity": "INFO",
  "userId": null,
  "details": {
    "tokenId": "tok_01HX9...",
    "deploymentName": "api-prod",
    "triggeredBy": "access_token"
  },
  "ipAddress": "198.51.100.22",
  "timestamp": "2026-04-21T23:42:17.000Z"
}

No userId — the stop was triggered by an Access Token, not a human session. tokenId identifies which token.

Step 2: Cross-reference the token ID against the token list.

nexus token list --json | jq '.[] | select(.id == "tok_01HX9...")'

Result: The token was named github-actions-prod. It has deploy:write scope. But the GitHub Actions workflow that uses it is only supposed to trigger redeployments, not stops.

Step 3: Pull the full recent activity for that token.

curl -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/logs?limit=20" | \
  jq '.data.logs[] | select(.details.tokenId == "tok_01HX9...")'

Result: The token was used from IP 198.51.100.22. Your CI/CD pipeline runs from 140.82.114.0/24. This IP is outside that range.

The token was compromised. You revoke it immediately, rotate secrets, and have a complete timeline of every action it took — from the first legitimate use to the unauthorized stop. The entire investigation took 11 minutes.

Without audit logs: that same investigation would have required GitHub Actions logs, cloud provider logs, and a manual timeline reconstruction. Best case: 90 minutes.

Compliance mapping

NEXUS AI's audit log maps directly to the access-control and audit requirements in the major compliance frameworks. This is not a marketing table — these are the specific control IDs your auditor will check.

HIPAA

HIPAA requirement	Control ID	NEXUS AI coverage
Access control — unique user identification	§164.312(a)(2)(i)	`userId` on every record; token-based access uses `tokenId` in `details`
Audit controls — hardware, software, procedural mechanisms	§164.312(b)	42 event types, append-only log, 90–365 day retention
Automatic logoff — session inactivity termination	§164.312(a)(2)(iii)	`TOKEN_EXPIRED` event records session termination
Encryption and decryption — PHI protection	§164.312(a)(2)(iv)	`SECRET_RUNTIME_ACCESSED` records every secret decryption event
Person or entity authentication — verify identity before granting access	§164.312(d)	`LOGIN_FAILED` events surface failed authentication

SOC 2 Type II

SOC 2 criterion	Trust Service Criterion	NEXUS AI coverage
Logical access controls	CC6.1	`PERMISSION_CHANGED`, `USER_CREATED`, `USER_DELETED`
System access authorization	CC6.2	`LOGIN_SUCCESS`, `LOGIN_FAILED`, `UNAUTHORIZED_ACCESS`
User registration and de-provisioning	CC6.3	`USER_CREATED`, `USER_DELETED`, `PERMISSION_CHANGED`
Restricting access to data in transit	CC6.7	`SECRET_RUNTIME_ACCESSED`, `DATABASE_ACCESSED`
Monitoring of system components	CC7.2	`HIGH_CPU_USAGE`, `HIGH_MEMORY_USAGE`, `RESOURCE_LIMIT_EXCEEDED`
Incident detection and reporting	CC7.3	`SUSPICIOUS_ACTIVITY`, `CONTAINER_ESCAPE_ATTEMPT` (CRITICAL, alerted immediately)

GDPR

GDPR requirement	Article	NEXUS AI coverage
Records of processing activities	Art. 30	Complete event log with timestamp, actor, resource, and outcome
Accountability — demonstrate compliance	Art. 5(2)	Append-only log with no modification capability
Data access requests — who accessed what	Art. 15	`user-activity/:userId` endpoint for per-user activity reports
Breach notification — detect and respond within 72 hours	Art. 33	CRITICAL events alerted immediately; `SUSPICIOUS_ACTIVITY` surfaces breach signals

PCI DSS (v4.0)

PCI DSS requirement	Control	NEXUS AI coverage
Track and monitor access to cardholder data	Req. 10.2	`DATABASE_ACCESSED`, `DATABASE_QUERY_EXECUTED` for connected payment databases
Record user access to audit trails	Req. 10.2.1	All 42 event types record `userId` or `tokenId`
Record privileged access	Req. 10.2.1.b	`PERMISSION_CHANGED` records role elevations
Retain audit log history for at least 12 months	Req. 10.7	Set `AUDIT_LOG_RETENTION_DAYS=365` on Enterprise
Review logs daily	Req. 10.6	`GET /api/audit/logs` with date filter; exportable to SIEM

Integrating with your SIEM

NEXUS AI does not require a native SIEM integration — the export API and JSON query endpoint are designed to plug into any pipeline.

Datadog:

# Pull last hour of WARNING+ events and ship to Datadog
curl -s -H "Authorization: Bearer $NEXUS_API_KEY" \
  "https://nexusai.run/api/audit/logs?severity=WARNING&startDate=$(date -u -v-1H '+%Y-%m-%dT%H:%M:%SZ')" | \
  jq '.data.logs[]' | \
  while read -r event; do
    curl -s -X POST "https://http-intake.logs.datadoghq.com/api/v2/logs" \
      -H "DD-API-KEY: $DD_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$event"
  done

Grafana / Loki: Ship the JSON response from /api/audit/logs via a log shipper (Promtail, Alloy) configured to poll the endpoint on a scheduled interval.

Splunk / SIEM: Use the CSV export endpoint (/api/audit/export) on a scheduled basis and ingest via Splunk's file monitor input.

On the Enterprise On-Prem plan, audit logs live in your PostgreSQL cluster. Query them directly with any BI or SIEM tool that supports PostgreSQL — no export pipeline required.

What the audit log does NOT record

Knowing the boundaries of any control is as important as knowing what it covers.

Secret values are never logged. SECRET_RUNTIME_ACCESSED records that a secret named DATABASE_URL was accessed for deployment api-prod. It does not record the value of DATABASE_URL. The plaintext never touches the audit log.

Application-level data is not recorded. NEXUS AI audits actions taken on the platform — deployments, secrets, members, tokens. It does not audit what your application does with the resources it receives. If your app logs process.env.DATABASE_URL at startup, that is an application-level concern, not a platform-level audit event.

Read operations on deployments are not individually logged. Viewing a deployment's status in the dashboard does not produce an audit event. Audit events capture state changes and security-relevant reads (secrets, databases). Routine dashboard reads would generate millions of low-value INFO events per day on active organizations.

Container stdout/stderr is not the audit log. Build logs and runtime logs are separate from the audit log. They are accessible via GET /api/deployments/:id/logs and stored in the observability layer, not in audit_logs.

Checklist: audit log hygiene

[ ] Review GET /api/audit/security-summary weekly — if the score drops below 80, investigate
[ ] Set AUDIT_LOG_RETENTION_DAYS=365 for HIPAA, financial, or PCI workloads (Enterprise plan)
[ ] Export monthly CSVs to your compliance archive before the quarterly close
[ ] Pull GET /api/audit/user-activity/:userId for every departing team member as part of offboarding
[ ] Filter for PERMISSION_CHANGED events during quarterly access reviews — verify every role change was intentional
[ ] Confirm no SECRET_REVEALED events in the last 30 days unless explicitly authorized
[ ] Set up a SIEM pipeline for severity=WARNING events if your team size exceeds 10 engineers
[ ] On Enterprise On-Prem: verify your PostgreSQL backup schedule includes the audit_logs table
[ ] Document your retention period in your security policy before your next audit

Frequently asked questions

Can I delete an audit log entry?

No. Audit log records are append-only. There is no API endpoint to delete individual records. The retention job purges records older than the retention window — but only non-CRITICAL events, and only automatically. This immutability is intentional: an audit log you can edit is not an audit log.

Who can access audit logs?

Audit log access requires the audit.read org permission, which is granted to OWNER and ADMIN roles. Developer and lower roles cannot query the audit log. This prevents a Developer from inspecting what other users have done — audit visibility is a privilege, not a default.

Does the audit log capture API calls made by NEXUS AI MCP tools (Claude agents)?

Yes. MCP tool calls go through the same API layer as CLI and dashboard actions. They produce audit events with the token ID in details.tokenId and a userAgent that identifies the MCP client. You can filter for agent-originated actions by querying for the specific token ID issued to your MCP integration.

What happens to audit logs if I downgrade my plan?

Logs are not deleted on plan downgrade. If you downgrade from Enterprise (365-day retention) to Pro (90-day retention), the retention job will begin purging records older than 90 days on its next daily run. Export before downgrading if you need records beyond the 90-day window.

Is the audit log encrypted at rest?

Yes. The audit_logs table lives in the same PostgreSQL database as the rest of your organization's data. The database is encrypted at rest using AES-256. On Enterprise On-Prem, encryption at rest is your infrastructure team's responsibility.

Can I receive real-time alerts for specific event types?

CRITICAL events (SUSPICIOUS_ACTIVITY, CONTAINER_ESCAPE_ATTEMPT) trigger the alert pipeline immediately. For custom alerting on other event types — for example, an alert any time PERMISSION_CHANGED fires — the current path is to poll /api/audit/logs via your SIEM and configure alert rules there. Native webhook delivery for specific event types is on the product roadmap.

What's next

The audit log is available on every NEXUS AI plan, including Starter at $29/mo. The 90-day retention window, CSV export, and full API access ship on all plans. Configurable retention windows (AUDIT_LOG_RETENTION_DAYS) and indefinite CRITICAL event retention are available on Enterprise and Enterprise On-Prem.

If you are working through a HIPAA Business Associate Agreement, SOC 2 audit, or PCI self-assessment questionnaire, the compliance table in this post maps directly to the evidence your auditor needs. The CSV export at /api/audit/export is the artifact.

For regulated workloads, healthcare data, or financial applications, the Enterprise plan adds configurable retention, dedicated security review, and SAML SSO. Reach out at nexusai.run.

Related reading:

Stop shipping secrets. Start using a vault.
RBAC deep dive: roles, scopes, and least privilege
MCP integration: 37 tools for Claude and AI agents
How NEXUS AI deploys your app in under 5 minutes

What you can't see, you can't defend. What you can't prove, you can't audit.

NEXUS AI GitHub Integration: The Complete Guide to Auto-Deploying from Your Repository

Saif Ali — Sun, 09 Aug 2026 13:27:38 +0000

NEXUS AI GitHub Integration: The Complete Guide to Auto-Deploying from Your Repository

Connecting your GitHub repository to NEXUS AI unlocks a fully automated deployment pipeline — push code, and your app is live within minutes on GCP Cloud Run, AWS ECS Fargate, Azure Container Apps, or NEXUS AI Container. This guide walks through every step: installing the GitHub App, binding a repo, configuring auto-deploy rules, and understanding the webhook system that powers it all.

Why Integrate GitHub with NEXUS AI?

Modern software teams live in GitHub. Your pull requests, code reviews, branch strategies, and release tags all live there — so your deployment pipeline should follow that same source of truth.

The NEXUS AI GitHub integration makes your repository the single trigger for deployments:

No manual image builds or docker push commands
No CI pipeline boilerplate to maintain
Branch-level control over which pushes trigger a deploy
Encrypted environment variables stored securely at the binding level
Full webhook audit trail — see every event NEXUS AI received from GitHub

Step 1: Install the NEXUS AI GitHub App

To connect GitHub to NEXUS AI, you need to install the NEXUS AI GitHub App on your GitHub account or organisation.

Log in to your NEXUS AI dashboard at nexusai.run.
Navigate to Integrations → GitHub (or open any project and click Connect GitHub).
Click the Connect GitHub button. You will be redirected to GitHub's App installation page.
Choose whether to install on your personal account or a GitHub organisation.
Select the repositories you want to grant access to (you can choose All repositories or restrict to specific ones).
Confirm the installation. GitHub will redirect you back to NEXUS AI with your installation ID automatically captured.

Required GitHub App Permissions

The NEXUS AI GitHub App requests the minimum permissions needed to operate:

Permission	Level	Purpose
Repository contents	Read	Clone source code to build containers
Webhook events	Push	Receive push notifications to trigger deployments

No write access to your repository is ever requested. NEXUS AI only reads code and listens for push events.

Step 2: Bind a Repository to a Deployment Target

Once the app is installed, you need to bind a GitHub repo to a deployment target in NEXUS AI. A binding links one branch (or set of branches) to one runtime environment with its own build configuration.

Creating a Repo Binding

In the NEXUS AI dashboard:

Go to Deployments → New Deployment or open an existing project.
Select GitHub as the source.
Choose your installed GitHub account/org and pick a repository from the dropdown.
Configure the binding options below.

Repo Binding Configuration Options

Each binding exposes the following fields:

Branch control

allowedBranches — JSON array of branch names allowed to trigger deployments. Example: ["main", "production"]. Pushes to any other branch are silently ignored.

Deployment behaviour

autoDeploy — Boolean. When true, every push to an allowed branch queues a deployment automatically. When false, you must trigger deploys manually.
projectId — Associate this binding with a NEXUS AI project for grouping and access control.

Build configuration

buildMode — Build strategy. NEXUS AI auto-detects the language and framework, or you can override it.
installCommand — Dependency installation step. Example: npm ci
buildCommand — Build step. Example: npm run build
startCommand — Container entrypoint. Example: node server.js
outputDir — Build output directory (used for static sites and SSR frameworks).
servicePort — The port your application listens on inside the container. Example: 3000

Runtime target

runtimeTarget — Where to deploy the container. Options:
- gcp_cloud_run — Google Cloud Run (serverless containers)
- aws_ecs_fargate — AWS ECS with Fargate (serverless containers)
- azure_container_apps — Azure Container Apps
- Container — NEXUS AI

Serving

subdomain — NEXUS AI-managed subdomain (e.g. myapp.nexusai.run)
customDomain — Your own domain (e.g. app.example.com)
envVars — Environment variables stored encrypted at rest. Never visible in logs or UI after saving.

Example: Node.js App to GCP Cloud Run

{
  "allowedBranches": ["main", "production"],
  "autoDeploy": true,
  "runtimeTarget": "gcp_cloud_run",
  "installCommand": "npm ci",
  "buildCommand": "npm run build",
  "startCommand": "node server.js",
  "servicePort": 3000,
  "subdomain": "myapp",
  "envVars": {
    "NODE_ENV": "production",
    "DATABASE_URL": "postgresql://..."
  }
}

Step 3: Enable Auto-Deploy from GitHub

Auto-deploying from GitHub is controlled by two settings working together: autoDeploy and allowedBranches.

With autoDeploy: true and allowedBranches: ["main"], the full deployment flow is:

You run git push origin main
GitHub sends a push event webhook to https://nexusai.run/api/github/webhook
NEXUS AI verifies the HMAC-SHA256 signature on the x-hub-signature-256 header to confirm the event is genuine
NEXUS AI checks if the pushed branch (main) is in your allowedBranches list
NEXUS AI checks that autoDeploy is enabled on the binding
A deployment job is queued and picked up by a worker (up to 5 concurrent builds per worker, polling every 2 seconds)
Your container is built from source and pushed to the target runtime
Status progresses through: queued → building → deploying → success (or failed)

Duplicate Commit Protection

NEXUS AI deduplicates deployments by commit SHA. If you push the same commit twice (e.g. via a force-push that does not change the tree), NEXUS AI will not re-deploy it. Additionally, if a newer commit arrives while an older one is still queued, the older job is superseded — you always deploy the latest code, never a stale intermediate commit.

Step 4: Manual Deployments

You do not have to rely on push webhooks. To trigger a deployment on demand:

Via the dashboard: Open the binding and click the Deploy button. NEXUS AI fetches the latest commit on the configured branch and queues a build.

Via the REST API:

curl -X POST https://nexusai.run/api/github/bindings/:bindingId/deploy \
  -H "Authorization: Bearer <your-api-token>"

Replace :bindingId with the UUID of your repo binding, visible in the binding detail page URL.

Step 5: Understanding the Webhook System

Every push event GitHub sends to NEXUS AI is recorded in the Webhook Deliveries tab of your binding. This gives you a full audit trail of what happened and why.

What You Can See

Field	Description
Delivery ID	GitHub's unique ID for the webhook delivery
Event type	Always `push` for deployment triggers
Status	`ok`, `ignored`, or `failed`
Reason	Why the event was ignored (if applicable)
Timestamp	When the event was received

Common "Ignored" Reasons

Reason	Meaning
`autoDeploy disabled`	The binding has `autoDeploy: false`
`branch not in allowedBranches`	The pushed branch is not in your allowed list
`installation suspended`	The GitHub App install was suspended by a GitHub admin
`duplicate commit`	This exact commit SHA was already deployed

The webhook endpoint is: https://nexusai.run/api/github/webhook

All payloads are verified using HMAC-SHA256 with a per-installation secret. Requests with an invalid or missing x-hub-signature-256 header are rejected immediately with no processing.

GitHub Actions Integration

NEXUS AI does not replace GitHub Actions — it complements it. A common pattern is to run your test suite in GitHub Actions and only deploy when tests pass, using the NEXUS AI manual deploy API as the final step:

# .github/workflows/deploy.yml
name: Test and Deploy

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Trigger NEXUS AI deployment
        run: |
          curl -X POST \
            "https://nexusai.run/api/github/bindings/$NEXUS_BINDING_ID/deploy" \
            -H "Authorization: Bearer $NEXUS_API_TOKEN" \
            -H "Content-Type: application/json"
        env:
          NEXUS_BINDING_ID: ${{ secrets.NEXUS_BINDING_ID }}
          NEXUS_API_TOKEN: ${{ secrets.NEXUS_API_TOKEN }}

Add NEXUS_BINDING_ID and NEXUS_API_TOKEN as GitHub Actions secrets in your repository settings (Settings → Secrets and variables → Actions). With this pattern, set autoDeploy: false on the NEXUS AI binding — deployments are controlled entirely by your Actions workflow, not raw push events.

Frequently Asked Questions

Q: Which GitHub plan do I need?
A: The NEXUS AI GitHub App works with free, Pro, Team, and Enterprise GitHub plans. It supports both personal accounts and organisations.

Q: Can I bind the same repo to multiple deployment targets?
A: Yes. You can create multiple bindings for the same repository — for example, one binding deploying main to production on GCP Cloud Run and another deploying staging to a Docker host.

Q: How do I rotate my webhook secret?
A: Reinstall or refresh the GitHub App connection from the NEXUS AI integrations page. A new installation ID and secret are generated automatically.

Q: Are environment variables secure?
A: Yes. All values stored in envVars on a binding are encrypted at rest using AES-256-GCM. They are injected into the container at runtime and never logged or exposed in the dashboard after the initial save.

Q: What happens if a deployment fails?
A: The deployment status is set to failed. Your previous deployment continues running — NEXUS AI uses a rolling deployment strategy and never takes down a live container until a healthy replacement is confirmed. Build logs are available in the Deployments tab and you can trigger a retry at any time.

Q: How do I disconnect GitHub?
A: You can suspend or uninstall the NEXUS AI GitHub App at any time from GitHub → Settings → Applications → Installed GitHub Apps. In-flight deployments will complete; all future webhooks will be rejected.

Q: Can I use GitHub integration with a monorepo?
A: Yes. Use the buildCommand and outputDir fields to scope the build to a specific package or subdirectory. For example: "buildCommand": "cd packages/api && npm run build".

Summary

The NEXUS AI GitHub integration connects your repository to a fully automated, cloud-native deployment pipeline in three steps: install the GitHub App, create a repo binding with your target runtime and build configuration, then enable autoDeploy. Every push to an allowed branch is cryptographically verified, deduplicated by commit SHA, and deployed — with a full webhook audit trail so you always know exactly what happened and why.

For questions or support, visit the NEXUS AI documentation or open a support ticket from your dashboard.

MCP-driven deploys: 5 tasks your Claude agent should be running for you

Saif Ali — Sun, 09 Aug 2026 13:25:45 +0000

MCP-driven deploys: 5 tasks your Claude agent should be running for you

Published: May 17, 2026
Category: AI · MCP · Operations
Reading time: 8 minutes
Author: NEXUS AI Team

Most Model Context Protocol servers are read-only. They let your AI agent search a codebase, list GitHub issues, or look up Linear tickets. That is useful. It is also where most agents stop.

NEXUS AI's MCP server is different. It exposes more than 50 write actions covering the full deployment lifecycle: build, deploy, scale, back up, restore, attach storage, query the database, fix schemas, roll back, and delete. Connect it to Claude Code, Cursor, Codex, or any MCP client, and your agent can run your infrastructure on your behalf.

This post walks through five concrete tasks worth handing to your agent today.

If your AI tools have only ever generated code for you, see also Your AI app is generated. Now how do you deploy it? for the full picture of what changes when the agent owns operations.

Setup: connect the NEXUS AI MCP server in 60 seconds

For Claude Desktop, add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nexus-ai": {
      "url": "https://nexusai.run/mcp",
      "headers": {
        "Authorization": "Bearer <your-nexus-token>"
      }
    }
  }
}

For Cursor, add the same server in Cursor Settings → MCP → Add server.

Generate a token at https://nexusai.run/app/tokens. Scopes follow deployments:read|create|delete, db:query|admin, secrets:read|manage, and similar boundaries. Start with read-only scopes if you want to watch the agent before giving it write access.

Restart your AI client. The 50+ NEXUS AI tools appear in its tool list.

Task 1: Deploy from a prompt

The classic case. You have a repository with working code. Tell the agent:

Deploy this repo to NEXUS AI. Use Postgres and Redis. Set the start command to uvicorn app:app --host 0.0.0.0 --port 8000.

The agent calls:

nexusai_deploy_source
  repo:           https://github.com/you/my-app.git
  framework:      python
  services:       [postgresql, redis]
  start_command:  "uvicorn app:app --host 0.0.0.0 --port 8000"

Five minutes later the agent reports back with the live URL, the masked database connection string, and the deployment ID. You did not write a Dockerfile. You did not touch a dashboard.

Why hand this over: the agent already has the repository context (it just wrote the code). It knows which framework, which port, which start command. The agent should know all of these without being told.

Task 2: Back up the database before a risky migration

Your agent is about to run a schema migration. The right ops habit is "snapshot first, migrate second, validate third, restore on failure." That used to be three terminals, two Slack messages, and a prayer. Now it is one prompt:

Before running the migration on my-ai-app, take a Postgres backup. If the migration fails, restore from the backup and roll back the deploy.

The agent runs:

1. nexusai_db_services_list                 → finds the postgres service id
2. nexusai_db_backup                        → triggers pg_dump, waits for SUCCESS
3. (runs your migration command)
4. nexusai_deploy_logs                      → reads runtime logs for errors
5a. (success) nexusai_db_backup_list        → confirms backup is on the retention list
5b. (failure) nexusai_db_restore            → restores from the backup
              nexusai_deploy_rollback       → rolls back to the previous release

Why hand this over: the failure path is the part humans forget to do under pressure. The agent always remembers.

Backups land at /var/lib/nexus-backups/<service>/ and are downloadable through nexusai_db_backup_download, which returns a signed URL with a 30 to 3600 second TTL.

Task 3: Diagnose a failing deploy from logs

A deployment is stuck in BUILDING or healthy but throwing 500s. Ask:

What is wrong with my-ai-app right now? Tail the last 200 log lines, identify the failure, and propose a fix.

The agent runs:

nexusai_deploy_status   → status, health, restart count, last error
nexusai_deploy_logs     → last 200 lines of build + runtime logs

It reads the actual stack trace, identifies the missing environment variable, the unhealthy upstream, or the failed migration, and replies with a targeted fix. If the fix is a code change, it edits the file in your IDE. If the fix is a secret, it calls nexusai_secrets_create. If the fix is a redeploy, it calls nexusai_deploy_redeploy.

Why hand this over: incident triage is the part of operations that scales worst with team size. An agent in the loop never forgets to check the logs first.

Task 4: Query the database without leaving chat

You want to know how many users signed up this week. You do not want to open psql. Ask:

How many users signed up in the last 7 days on my-ai-app?

The agent runs:

1. nexusai_db_source_list           → resolves your database service
2. nexusai_db_inspect_schema        → confirms there is a `users` table with `created_at`
3. nexusai_db_query_preview         → returns the SQL it intends to run, you approve
4. nexusai_db_query_execute         → runs the read-only query, returns the count

The preview step is the safety net. You see the SQL before it runs. For read-only queries the agent runs in a sandboxed session with a 5-second statement timeout and a row-count cap. For destructive queries the agent uses the AI-powered DDL fix workflow (nexusai_db_propose_fix then nexusai_db_apply_fix), which requires explicit approval.

Why hand this over: most "look at the database" tasks are short, repetitive, and high-friction. Making them a chat message removes the friction.

Task 5: Roll back on incident

A deploy went out at 3pm. Error rates spiked at 3:05. Tell the agent:

Roll back my-ai-app to the previous release. Snapshot Postgres first in case we need to forward-fix.

The agent runs:

1. nexusai_db_backup           → snapshot before the rollback
2. nexusai_deploy_rollback     → revert to the previous container image
3. nexusai_deploy_status       → confirm RUNNING and healthy
4. nexusai_deploy_logs         → tail to verify error rate dropped

Rollback flips back to the previous image with the same database state. If the bug was schema-level you can restore from the backup separately.

Why hand this over: rollbacks under stress are exactly when humans skip the snapshot step.

What you should not hand over yet

A few actions are deliberately gated. The agent can prepare them but cannot fire them without explicit confirmation:

Action	Why gated
Delete a deployment (`nexusai_deploy_delete`)	Permanent. Tears down containers, networks, volumes.
Drop or truncate via `nexusai_db_query_execute`	Requires `db:admin` scope and an explicit confirmation.
Delete a bucket (`nexusai_bucket_delete`)	Removes scoped service account and bucket contents.
Remove a volume (`nexusai_volume_delete`)	Deletes the underlying data.
Rotate bucket credentials	Invalidates current keys. Apps must redeploy.

The platform requires the agent to call a _preview variant first (where available) or to set an explicit confirm: true flag. The agent will pause and ask you before crossing one of these lines.

A minimal Claude system prompt for operations

If you want Claude to behave as a careful operator rather than an enthusiastic deployer, paste this into your project's system instructions:

You are operating a NEXUS AI account via MCP tools. Rules:

1. Read before you write. Always call status/list/inspect tools before
   making changes.
2. Snapshot before destructive operations. Always call nexusai_db_backup
   before migrations or restores.
3. Show the SQL before running it. Always call nexusai_db_query_preview
   before nexusai_db_query_execute.
4. Confirm before deletes. Never call delete tools without an explicit
   "yes, delete <resource>" from the user in the same message.
5. Prefer rollback over fix-forward during an incident. Stabilize first,
   debug second.
6. Stream logs after every deploy or restart and summarize the first
   error you see.

Six lines turn a code-generating agent into an operations partner.

What this changes about your workflow

Once the agent can deploy and operate, three things shift:

Operations cost drops. Tasks that took 5 to 30 minutes (snapshot, deploy, tail logs, rollback) become one prompt. The agent does the boilerplate, you make the decision.

Incident response gets faster. The agent already has context (recent code changes, recent deploys, recent logs). It can triage in seconds instead of minutes.

Experimentation gets cheaper. Standing up a new app, attaching a database, testing an idea, tearing it down: each step is one prompt instead of one ticket.

The agent is no longer a code-completion tool. It is the operator on call.

FAQ

Which MCP clients work with NEXUS AI?
Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf, Zed AI, and any client that speaks MCP over HTTP or stdio. NEXUS AI publishes a hosted HTTPS endpoint, so any client that can attach a Bearer token works.

Does the agent need the same permissions I have?
No. NEXUS AI tokens are scoped. Start the agent with deployments:read, db:read, logs:read. Promote scopes only when you want it to deploy or modify. Tokens are revocable from the dashboard.

Can two agents operate the same account?
Yes. Each token is independent. Audit log entries record which token took each action, so you can attribute changes to "claude-prod", "cursor-staging", or any other label.

Is there a rate limit on MCP calls?
The platform applies standard API rate limits per token. Heavy reconciliation loops should batch (*_list tools support pagination) instead of polling.

Does the agent see secret values?
No. nexusai_secrets_list returns names and metadata. nexusai_secrets_create accepts values you provide. The platform never returns decrypted secret values over the API or MCP.

What if the agent makes a mistake?
Every action is in the audit log (AuditLog table, exportable from the dashboard). Most actions are reversible: stops have starts, deploys have rollbacks, backups have restores. Deletes are the only one-way door, and the agent will not call delete tools without explicit user confirmation in the same message.

Start free and connect the MCP server in your client of choice. Or ask your agent to do it for you.

Persistent storage in NEXUS AI

Saif Ali — Sun, 09 Aug 2026 13:24:13 +0000

Persistent storage in NEXUS AI: volumes and S3-compatible buckets for deployed apps

Published: May 9, 2026

Category: Storage · DevOps

Reading time: 11 minutes

Author: NEXUS AI Team

Most application deployment platforms make stateless services easy and stateful workloads awkward. That works until your app needs user uploads, generated reports, SQLite files, model artifacts, or a shared object store for background jobs.

NEXUS AI now includes two storage primitives for deployed applications:

Volumes for persistent filesystem mounts.
Buckets for S3-compatible object storage.

Both are organization-scoped. Both can be attached to deployments. Both survive container restarts, redeploys, and deployment deletion until you explicitly delete the storage resource.

This post explains when to use each one, how to attach them, how they behave during scaling, and the exact CLI commands to run.

Two storage primitives

Volumes and buckets solve different problems.

Feature	Best for	Access pattern	Attachment model
Volumes	Filesystem state, SQLite, local uploads, persistent caches	App reads and writes a mounted path like `/data`	Single deployment
Buckets	User media, reports, generated assets, object storage	App uses S3-compatible SDK calls	Multiple deployments

Use a volume when your app expects a local filesystem path.

Use a bucket when your app can store data as objects by key using an S3 SDK.

Volumes: persistent filesystem mounts

A NEXUS AI volume is a persistent filesystem mount backed by a Docker named volume. Your app writes to a path, usually /data, and the data remains available after redeploys or container replacement.

Create a volume:

nexus volume create app-data --display-name "App data"

Deploy your app:

nexus deploy source \
  --repo https://github.com/your-org/your-app \
  --name myapp \
  --provider docker \
  --wait

Attach the volume:

nexus volume attach <volume-id> <deployment-id> --mount /data

Redeploy so the new container starts with the mount:

nexus deploy redeploy <deployment-id> --wait

That redeploy step matters. Docker mounts are applied when a container is created. You cannot add a volume mount to an already-running container.

Verify the mount:

docker exec <container-id> ls -la /data

When to use volumes

Volumes are a good fit for:

SQLite databases for small apps.
User uploads written through the filesystem.
Persistent cache directories.
Generated files that your app expects to read from disk.
Model files or local indexes that survive redeploys.

Volumes are not a good fit for every scaled workload. If multiple app replicas write the same file at the same time, your application needs to handle locking or coordination.

Think of a NEXUS AI volume like a shared network drive. It persists, but it does not magically make unsafe concurrent writes safe.

How volumes behave when you scale

When you scale a deployment up, every replica mounts the same named volume at the same path.

nexus deploy scale <deployment-id> 3

All three replicas now see the same files under /data.

That is useful for read-mostly data, shared assets, or workloads with explicit locking. It is risky for apps that assume a single writer, such as a default SQLite setup with multiple write-heavy replicas.

When you scale down:

nexus deploy scale <deployment-id> 1

The removed containers detach. The volume remains. The remaining replica keeps using the same data.

When you delete the deployment, the volume still survives. You must explicitly detach and delete the volume if you want to destroy the data.

nexus volume detach <volume-id>
nexus volume delete <volume-id> --yes

Buckets: S3-compatible object storage

A NEXUS AI bucket is S3-compatible object storage backed by MinIO. Your app interacts with it using standard AWS SDKs, boto3, or any S3-compatible client.

Create a bucket:

nexus bucket create user-uploads --display-name "User uploads"

Attach it to a deployment:

nexus bucket attach <bucket-id> <deployment-id>
nexus deploy redeploy <deployment-id> --wait

After redeploy, NEXUS AI injects S3 environment variables into the app container:

S3_ENDPOINT=http://host.docker.internal:9000
S3_REGION=us-east-1
S3_BUCKET=org-<orgIdShort>-<bucketName>
S3_ACCESS_KEY=<scoped access key>
S3_SECRET_KEY=<scoped secret key>

If multiple buckets are attached, NEXUS AI also injects per-bucket aliases:

S3_BUCKET_USER_UPLOADS=org-...-user-uploads
S3_BUCKET_USER_UPLOADS_ACCESS_KEY=...
S3_BUCKET_USER_UPLOADS_SECRET_KEY=...

Example: write files to a bucket from Python

Your app can use boto3 with the injected environment variables:

import os
import boto3

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
    region_name=os.environ["S3_REGION"],
)

s3.put_object(
    Bucket=os.environ["S3_BUCKET"],
    Key="uploads/hello.txt",
    Body=b"hello from NEXUS AI",
)

That same pattern works with the AWS SDK for JavaScript, Go, Java, Ruby, PHP, and other S3-compatible clients.

Bucket file operations from the CLI

List files:

nexus bucket files <bucket-id>
nexus bucket files <bucket-id> --prefix uploads/

Upload a file:

nexus bucket upload <bucket-id> ./report.pdf --key reports/report.pdf

Download a file:

nexus bucket download <bucket-id> reports/report.pdf --out ./report.pdf

Generate a short-lived signed download URL:

nexus bucket download <bucket-id> reports/report.pdf --share --ttl 900

Delete a file:

nexus bucket rm <bucket-id> reports/report.pdf --yes

The CLI upload path streams from disk, which is better for large files than browser uploads.

Scoped credentials and rotation

Each bucket gets scoped S3 credentials. A deployment attached to one bucket does not automatically get access to every bucket in the organization.

Reveal credentials for external clients:

nexus bucket credentials <bucket-id>

Rotate credentials:

nexus bucket rotate-credentials <bucket-id> --yes
nexus deploy redeploy <deployment-id> --wait

Redeploy is required because the running container already has the old environment variables. The next container start receives the new S3_ACCESS_KEY and S3_SECRET_KEY.

Buckets and scaling

Buckets are usually a better fit for scaled apps than shared filesystem volumes.

When you scale up, every replica receives the same S3 environment variables. Each replica makes independent S3 API calls. The object storage layer handles concurrent requests.

nexus deploy scale <deployment-id> 3

For object keys, the normal S3 rule applies: if two replicas write the same key, the last write wins. Use unique keys when each replica should produce independent output.

When you scale down, nothing needs to detach. The removed container stops making S3 calls. The bucket and objects remain.

REST API reference

Volumes:

GET    /api/volumes
POST   /api/volumes
POST   /api/volumes/:id/attach
POST   /api/volumes/:id/detach
POST   /api/volumes/:id/refresh-usage
DELETE /api/volumes/:id

Buckets:

GET    /api/buckets
POST   /api/buckets
POST   /api/buckets/:id/attach
POST   /api/buckets/:id/detach
POST   /api/buckets/:id/refresh-usage
POST   /api/buckets/:id/rotate-credentials
GET    /api/buckets/:id/credentials
GET    /api/buckets/:id/files
PUT    /api/buckets/:id/files/:key
GET    /api/buckets/:id/files/:key/download
POST   /api/buckets/:id/files/:key/download-url
DELETE /api/buckets/:id/files/:key
GET    /api/bucket-downloads/:token

Example volume attach request:

curl -s -X POST "$NEXUS_API_BASE/volumes/<volume-id>/attach" \
  -H "Authorization: Bearer $NEXUS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"deploymentId":"<deployment-id>","mountPath":"/data"}'

Example bucket attach request:

curl -s -X POST "$NEXUS_API_BASE/buckets/<bucket-id>/attach" \
  -H "Authorization: Bearer $NEXUS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"deploymentId":"<deployment-id>"}'

MCP tools

AI clients can operate storage through MCP tools with scoped permissions.

Volume tools:

nexusai_volume_list
nexusai_volume_create
nexusai_volume_attach
nexusai_volume_detach
nexusai_volume_delete

Bucket tools:

nexusai_bucket_list
nexusai_bucket_create
nexusai_bucket_attach
nexusai_bucket_detach
nexusai_bucket_rotate_credentials
nexusai_bucket_files_list
nexusai_bucket_file_download
nexusai_bucket_file_delete
nexusai_bucket_delete

Use MCP for operational flows like “create a bucket for this deployment, attach it, then remind me to redeploy,” while keeping destructive operations behind confirmation.

Which one should you choose?

Choose a volume when:

Your app requires a filesystem path.
You need persistent local files.
You are running a single replica or have safe file-locking behavior.
You want simple persistence for Docker-based deployments.

Choose a bucket when:

Your app stores uploads or generated files.
Multiple deployments need access to the same storage.
The app may scale to multiple replicas.
You want S3-compatible tooling and signed URLs.

For most user-upload and generated-asset workflows, buckets are the better long-term default. For apps that truly expect local disk, volumes are the practical answer.

Final takeaway

NEXUS AI now gives deployed apps durable storage without forcing every app into the same model.

Volumes give you persistent filesystem mounts. Buckets give you S3-compatible object storage with scoped credentials, file operations, signed URLs, and multi-deployment attachment.

The rule is simple: use volumes for local filesystem state, and use buckets for object storage. Then redeploy after attaching so your containers receive the mount or environment variables they need.

Deploy a full-stack Python app with Postgres, Redis, and workers in 5 minutes

Saif Ali — Sun, 09 Aug 2026 13:21:53 +0000

Deploy a full-stack Python app with Postgres, Redis, and workers in 5 minutes

Published: May 15, 2026

Category: Python · DevOps · Databases

Reading time: 8 minutes

Author: NEXUS AI Team

Most Python apps are not just one web process.

Even a small production app usually needs:

A web API, often FastAPI, Flask, or Django.
PostgreSQL for durable application data.
Redis for queues, caching, rate limits, or sessions.
A background worker for slow jobs like emails, scraping, AI calls, imports, PDF generation, or webhook processing.

The painful part is usually not the code. It is wiring the app container, database, cache, worker process, service networking, ports, health checks, environment variables, volumes, logs, and scaling rules.

With the NEXUS AI CLI, you can deploy the whole stack from a Git repository with one command.

This post walks through a practical Python deployment using:

Python web app
PostgreSQL service
Redis service
RQ background worker
Internal service networking
Scaling
Logs
Backup

What we are deploying

The target architecture looks like this:

Internet
  |
  v
NEXUS AI 
  |
  v
Python web container
  |-- connects to postgresql:5432
  |-- connects to redis:6379
  |
  v
Worker container
  |-- runs rq worker default
  |-- connects to the same Postgres and Redis services

PostgreSQL container
Redis container

The important detail: the app and worker do not connect to localhost.

Inside the deployment network, the database hostnames are:

postgresql:5432
redis:6379

NEXUS AI injects the environment variables your app needs, including DATABASE_URL and REDIS_URL.

Prerequisites

You need:

A NEXUS AI account.
The NEXUS CLI installed.
A Git repository containing your Python app.
A Python app that listens on a known port, usually 8000.

Install the CLI:

curl -fsSL https://nexusai.run/install.sh | bash

On macOS:

curl -fsSL https://nexusai.run/install-mac.sh | bash

Authenticate:

nexus auth login
nexus auth status

Example Python app structure

Your repository can be simple:

my-python-app/
  app.py
  worker.py
  requirements.txt

Example requirements.txt:

fastapi
uvicorn[standard]
psycopg[binary]
redis
rq

Example app.py:

import os
from fastapi import FastAPI
from redis import Redis
from rq import Queue

app = FastAPI()

redis_conn = Redis.from_url(os.environ["REDIS_URL"])
queue = Queue("default", connection=redis_conn)


def run_task(name: str):
    return f"processed {name}"


@app.get("/healthz")
def healthz():
    return {"ok": True}


@app.post("/jobs/{name}")
def enqueue_job(name: str):
    job = queue.enqueue(run_task, name)
    return {"job_id": job.id, "status": "queued"}

Example worker.py:

import os
from redis import Redis
from rq import Worker, Queue

redis_conn = Redis.from_url(os.environ["REDIS_URL"])
worker = Worker([Queue("default", connection=redis_conn)], connection=redis_conn)

worker.work()

For a real app, your task functions usually live in a separate module so both the web process and worker can import them cleanly.

Deploy the full stack

Run one command:

nexus deploy source \
  --repo https://github.com/your-org/my-python-app.git \
  --name my-python-app \
  --provider docker \
  --framework python \
  --branch main \
  --services postgresql,redis \
  --start-command "uvicorn app:app --host 0.0.0.0 --port 8000" \
  --worker-command "python worker.py" \
  --worker-name jobs-worker \
  --wait

That command does the operational work:

Pulls your Git repository.
Detects/builds the Python app image.
Creates the web app container.
Creates a PostgreSQL service.
Creates a Redis service.
Creates a worker container from the same app image.
Attaches the app, worker, Postgres, and Redis to the same service network.
Injects database and Redis environment variables.
Exposes only the web app publicly.
Keeps the worker private.

The worker does not need a public port. It runs inside the same deployment network and talks to Redis/Postgres by internal hostname.

Environment variables your app receives

For PostgreSQL:

POSTGRES_HOST=postgresql
POSTGRES_PORT=5432
POSTGRES_DB=appdb
POSTGRES_USER=appuser
POSTGRES_PASSWORD=<generated>
DATABASE_URL=postgresql://appuser:<generated>@postgresql:5432/appdb

For Redis:

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_URL=redis://redis:6379/0

Use these values inside the app and worker.

Do not hardcode:

localhost
127.0.0.1
host.docker.internal

Those point to the wrong place from inside a container. Use postgresql and redis.

Check deployment status

nexus deploy status my-python-app

You should see the deployment move through states such as:

PENDING
BUILDING
RUNNING

When it is running, open the deployment URL and check the health route:

curl https://your-app-url/healthz

Expected response:

{"ok":true}

Watch app and worker logs

Tail logs:

nexus deploy logs my-python-app --follow

If your worker is connected correctly, you should see it listening on the queue:

Listening on default...

If the worker cannot resolve Redis, you will see errors like:

Error -2 connecting to redis:6379. Name or service not known.

That usually means the worker was not attached to the deployment network or the app is using the wrong Redis hostname.

Use REDIS_URL=redis://redis:6379/0, not localhost.

Test the queue

Send a job to the web app:

curl -X POST https://your-app-url/jobs/demo

Expected response:

{
  "job_id": "...",
  "status": "queued"
}

Then check logs:

nexus deploy logs my-python-app --follow

You should see the worker pick up the job.

Scale the web app

Scale the web containers to two replicas:

nexus deploy scale my-python-app 2

Scale to three:

nexus deploy scale my-python-app 3

Scale back down:

nexus deploy scale my-python-app 1

Scaling changes the web app replicas. PostgreSQL and Redis are not duplicated. They remain the shared backing services for the deployment.

This matters because a scaled Python app should be stateless at the web layer:

Store durable data in Postgres.
Store queue/cache/session data in Redis.
Store uploaded files in a bucket or attached volume.
Do not rely on local container files unless you intentionally attached persistent storage.

Add production environment variables

Pass runtime variables directly:

nexus deploy source \
  --repo https://github.com/your-org/my-python-app.git \
  --name my-python-app \
  --provider docker \
  --framework python \
  --services postgresql,redis \
  --env APP_ENV=production \
  --env QUEUE_NAME=default \
  --worker-command "python worker.py" \
  --wait

Or load them from a file:

nexus deploy source \
  --repo https://github.com/your-org/my-python-app.git \
  --name my-python-app \
  --provider docker \
  --framework python \
  --services postgresql,redis \
  --env-file .env.production \
  --worker-command "python worker.py" \
  --wait

For sensitive values, use the secrets vault instead of committing .env files.

nexus secret create OPENAI_API_KEY

Then reference secrets during deployment or from the dashboard, depending on your workflow.

Back up Postgres

List database services:

nexus db services my-python-app

Create a backup:

nexus db backup <postgres-service-id>

List backups:

nexus db backups <postgres-service-id>

Download a backup:

nexus db backup-download <postgres-service-id> <backup-id> --out ./postgres.dump

Restore into the same service:

nexus db restore <postgres-service-id> <backup-id> --yes

Restore into another deployment's Postgres service in the same organization:

nexus db restore-to <target-postgres-service-id> <backup-id> --yes

Before restoring production data, pause write-heavy workers or scale them down if your workflow supports it. A restore can replace database state.

Common fixes

The app cannot connect to Postgres

Check that the app is using:

DATABASE_URL=postgresql://appuser:<password>@postgresql:5432/appdb

The hostname must be postgresql.

The worker cannot connect to Redis

Check that the worker is using:

REDIS_URL=redis://redis:6379/0

The hostname must be redis.

The worker starts, then exits

Make sure the worker command is a long-running process:

--worker-command "python worker.py"

or:

--worker-command "rq worker default"

Do not use a one-shot command unless you intentionally want a short task.

The app deploys, but health checks fail

Confirm the app listens on 0.0.0.0, not 127.0.0.1:

uvicorn app:app --host 0.0.0.0 --port 8000

Also make sure the app exposes a health endpoint such as:

/healthz

Scaling up works, but file uploads disappear

Local container files are ephemeral. Use a NEXUS AI bucket for user uploads or a persistent volume for filesystem-backed data.

For object storage:

nexus bucket create user-uploads --display-name "User uploads"
nexus bucket attach <bucket-id> <deployment-id>
nexus deploy redeploy <deployment-id> --wait

The 5-minute path

If your app already has a working Python web process and worker command, the full deployment is one command:

nexus deploy source \
  --repo https://github.com/your-org/my-python-app.git \
  --name my-python-app \
  --provider docker \
  --framework python \
  --services postgresql,redis \
  --start-command "uvicorn app:app --host 0.0.0.0 --port 8000" \
  --worker-command "python worker.py" \
  --worker-name jobs-worker \
  --wait

Then verify:

nexus deploy status my-python-app
nexus deploy logs my-python-app --follow
curl https://your-app-url/healthz

That is the core workflow: deploy the web app, provision Postgres and Redis, attach the worker to the same network, and manage the whole stack from the CLI.

FAQ

Can I use Celery instead of RQ?

Yes. Use a Celery worker command:

--worker-command "celery -A app.celery worker --loglevel=info"

Does the worker get the same environment variables as the app?

Yes. The worker uses the same built image and receives the same deployment environment variables, including database and Redis connection values.

Does scaling duplicate Postgres or Redis?

No. Scaling changes app replicas. Database and cache services remain shared deployment resources.

Should the worker expose a port?

No. Workers should stay private. They consume jobs from Redis and do not need public ingress.

Can I deploy Django with this pattern?

Yes. Use a Django web command such as gunicorn config.wsgi:application --bind 0.0.0.0:8000 and a worker command such as celery -A config worker --loglevel=info.

Can I use this with private GitHub repositories?

Yes. Store your repository token as a secret and deploy with --repo-secret.

nexus deploy source \
  --repo https://github.com/your-org/private-python-app.git \
  --repo-secret GITHUB_TOKEN \
  --name private-python-app \
  --provider docker \
  --framework python \
  --services postgresql,redis \
  --worker-command "python worker.py" \
  --wait

Replace Github Actions With One Command

Saif Ali — Sun, 09 Aug 2026 13:18:49 +0000

My GitHub Actions deploy workflow was 87 lines of YAML.

It had grown over 18 months from a clean 20-line file into something I was genuinely afraid to touch. It broke whenever a dependency updated. It had three hardcoded ARNs from an AWS account I was no longer using. It had a comment that said # TODO: fix this that had been there for 11 months.

Last month I deleted all 87 lines and replaced them with one command.

Here's exactly how I did it — and what I learned along the way.

The YAML graveyard

This was my deploy workflow. See if any of this feels familiar:

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v1

      - name: Build Docker image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t $ECR_REGISTRY/my-app:$IMAGE_TAG .
          docker push $ECR_REGISTRY/my-app:$IMAGE_TAG
          echo "IMAGE=$ECR_REGISTRY/my-app:$IMAGE_TAG" >> $GITHUB_ENV

      - name: Download task definition
        run: |
          aws ecs describe-task-definition --task-definition my-app \
            --query taskDefinition > task-definition.json

      - name: Update ECS task definition
        id: task-def
        uses: aws-actions/amazon-ecs-render-task-definition@v1
        with:
          task-definition: task-definition.json
          container-name: my-app
          image: ${{ env.IMAGE }}

      - name: Deploy to ECS
        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
        with:
          task-definition: ${{ steps.task-def.outputs.task-definition }}
          service: my-app-service
          cluster: my-app-cluster
          wait-for-service-stability: true

      - name: Notify on failure
        if: failure()
        run: |
          curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
            -H 'Content-type: application/json' \
            --data '{"text":"Deploy failed! Check Actions."}'

I wrote this. I'm not proud of it.

The real problem wasn't the YAML itself. The problem was everything hidden underneath the YAML:

An ECR repository I had to provision manually
An ECS cluster, service, and task definition I had to set up in the console
IAM roles with the exact right permissions (I guessed wrong twice)
A Dockerfile I maintained separately
AWS credentials rotated manually every 90 days

The pipeline was the visible part. The invisible part was 3 days of setup I did 18 months ago that I could no longer remember well enough to recreate.

When a new teammate joined and asked "how does deploy work?" — I sent them the workflow file and said "it's complicated."

That's not an answer. That's a warning sign.

The breaking point

In February, I switched from Node 18 to Node 20. The Docker build broke because my base image was pinned to node:18-alpine in three different places — the Dockerfile, the Actions workflow, and a .nvmrc file I had forgotten existed.

The fix took 45 minutes. The error message was not helpful. I fixed it by diffing my Dockerfile against a Stack Overflow answer from 2023.

Two weeks later, AWS deprecated the amazon-ecs-render-task-definition@v1 action. The pipeline broke silently — it ran, reported success, but the new image never actually deployed. I found out because a user filed a bug for something I had definitely already fixed.

That was the moment I decided: the pipeline is not worth maintaining.

What I tried first

I looked at Render and Railway. Both are good products. Neither deploys into my own AWS account — they provision their own infrastructure. My company has a compliance requirement that customer data stays in a customer-owned AWS environment. So those were out.

I looked at AWS CodePipeline. I wanted to solve complexity, not add more of it.

Then a colleague mentioned NEXUS AI. He described it as "a CLI that handles all the ECS stuff so you don't have to." I was skeptical. That's what everyone says.

The initial deploy

I installed the CLI:

npm install -g @nexusai/cli
nexus login

Then I pointed it at my repo:

nexus deploy source \
  --repo https://github.com/myorg/my-app \
  --name my-app \
  --provider aws_ecs_fargate

I expected this to fail immediately. My expectations for new DevOps tools are calibrated by years of experience.

It didn't fail. Four and a half minutes later I got back a URL. The app was running. The same app. In my AWS account.

I checked the AWS console out of habit. There was an ECS cluster. A task definition. A service. An ECR repository with the image in it. NEXUS AI had provisioned all of it.

I had not written a Dockerfile. I had not configured any IAM roles. I had not touched the AWS console.

I sat with that for a moment.

What actually happens under the hood

Here's what nexus deploy source does, in order:

Reads your repo — detects the runtime from package.json, requirements.txt, go.mod, etc.
Builds the container on NEXUS AI's build infrastructure — not your machine, not a GitHub runner
Pushes the image to an ECR repository it provisions in your account
Creates (or updates) the ECS infrastructure — cluster, task definition, service, load balancer
Issues a TLS certificate via ACM and wires it to the load balancer
Waits for health checks to pass before returning the live URL

Steps 3–5 are the 3 days of manual work I did 18 months ago. They now run in parallel and take about 3 minutes.

The new GitHub Actions workflow

Here's my deploy workflow today:

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: nexus deploy redeploy --deployment-id ${{ secrets.NEXUSAI_DEPLOYMENT_ID }}
        env:
          NEXUSAI_TOKEN: ${{ secrets.NEXUSAI_TOKEN }}

24 lines, including name: fields and blank lines.

The deploy job has one step. It calls nexus deploy redeploy, which tells NEXUS AI to rebuild from the latest commit and roll it out with a rolling update. No Docker commands. No AWS credentials. No ECR. No ECS task definition wrangling.

I kept the test job. NEXUS AI doesn't replace your test suite — it replaces everything after tests pass.

Secrets and environment variables

Before, I had secrets in three places: GitHub Actions secrets (for the pipeline), AWS Secrets Manager (for the app), and a .env.example file that was always slightly out of date.

Now:

nexus secret set \
  DATABASE_URL=postgres://user:pass@host/db \
  STRIPE_SECRET_KEY=sk_live_... \
  NODE_ENV=production

These are encrypted at rest and injected as environment variables when the container starts. The pipeline only needs NEXUSAI_TOKEN — one secret instead of seven.

After updating secrets, one command applies them:

nexus deploy redeploy --deployment-id <your-deployment-id>

Rollback

Old workflow rollback: figure out the previous image SHA, manually update the ECS task definition, trigger a new deployment, hope the old image hasn't been cleaned up by the ECR lifecycle policy.

New rollback:

nexus deploy rollback --deployment-id <your-deployment-id>

Reverts to the previous container image. Health checks run. Done. I've used this twice. Both times took under 90 seconds.

Redeployment speed

First deploy: ~4.5 minutes (infrastructure provisioning included).

Subsequent deploys: 60–90 seconds. Infrastructure is already provisioned, so it's just build → push → rolling update.

My old pipeline took 10–12 minutes. Most of that was the Docker build running on GitHub's shared runners plus the ECS service stability wait.

What I lost

Every tool has trade-offs. These are the real ones:

Less visibility into the build environment. With a Dockerfile I wrote, I knew exactly what was in the image. With source-based deployment, NEXUS AI generates the image. You can inspect it — nexus deploy logs gives the full build output — but you're not authoring the Dockerfile. For most apps this is fine. If you have specific system dependencies (custom C extensions, obscure shared libraries), test carefully.

The first deploy takes time. Infrastructure provisioning isn't instant. If you need sub-30-second cold deploys for some reason, this isn't that. But once infrastructure exists, redeployments are fast.

You're adding a dependency. NEXUS AI is now in your deploy path. Worth knowing.

The numbers

	Old workflow	New workflow
Lines of YAML	87	24
Pipeline runtime	10–12 min	60–90 sec
AWS console setup	~3 days (one-time)	0
Secrets locations	3	1
Rollback steps	~6 manual steps	1 command
Last random breakage	November	Hasn't happened

How to try it

# Install
npm install -g @nexusai/cli

# Authenticate
nexus login

# First deploy — detects Node/Python/Go automatically, no Dockerfile needed
nexus deploy source \
  --repo https://github.com/your/repo \
  --name my-app \
  --provider aws_ecs_fargate   # or gcp_cloud_run, azure_container_apps

# Check status
nexus deploy status --deployment-id <id>

# Set environment variables
nexus secret set KEY=value KEY2=value2

# Redeploy (use this in CI)
nexus deploy redeploy --deployment-id <id>

# Rollback
nexus deploy rollback --deployment-id <id>

For CI/CD: add NEXUSAI_TOKEN and NEXUSAI_DEPLOYMENT_ID as secrets in your GitHub repo settings, then replace your deploy steps with the one-liner from the workflow above.

Final thought

The 87-line YAML file wasn't the real cost. The real cost was the cognitive overhead of owning it — the 45-minute debugging session when Node versions drifted, the silent failure when an Action was deprecated, the "it's complicated" I sent to a new teammate.

I don't miss any of that.

If you're maintaining a pipeline like the one I had, it's worth spending 20 minutes to find out how much of it you can delete.

Building something and want to compare notes? Drop it in the comments.

Full-Stack Deployment on NEXUS AI: Frontend, Backend, and Database in One Command

Saif Ali — Sun, 09 Aug 2026 13:15:20 +0000

Shipping a full-stack application used to mean writing a Compose file by hand, generating passwords, wiring service names into environment variables, and hoping the health checks fired in the right order. NEXUS AI handles all of that. One command deploys your code alongside a database, connects them on a private network, and injects the credentials your app needs to connect.

How it works

When you deploy from source using nexusai_deploy_source (or nexus deploy source in the CLI) with a services array, NEXUS AI calls composeService.ts internally to generate a docker-compose.yml for your stack. Every service runs in the same private Docker network (deploy-network-{deploymentId}), so your app container reaches the database by service name rather than IP address.

Database volumes are named {serviceType}-data-{deploymentId} and persist across container restarts and redeploys. Your data survives unless you explicitly destroy the deployment.

Health checks gate startup. Your application container does not start until the database passes its readiness check:

PostgreSQL: pg_isready
MySQL: mysqladmin ping
MongoDB: mongosh --eval db.adminCommand("ping")
Redis: redis-cli ping

This means your app never boots into a state where the database is still initializing.

Database credentials are generated at deploy time with random passwords. You do not set them. NEXUS AI injects them directly into your containers as environment variables.

Supported database services

Service	Image	Default version
PostgreSQL	`postgres`	15-alpine
MySQL	`mysql`	8.0
MongoDB	`mongo`	7
Redis	`redis`	7-alpine

Deploying from source with a database

Via the CLI

nexus deploy source --repo https://github.com/your/repo \
  --name my-app \
  --services postgresql \
  --environment production \
  --provider docker
  --json

Multiple services:

nexus deploy source https://github.com/your/repo \
  --name my-app \
  --services postgresql,redis \
  --environment production

Via the MCP tool

{
  "tool": "nexusai_deploy_source",
  "input": {
    "repoUrl": "https://github.com/your/repo",
    "name": "my-app",
    "environment": "PRODUCTION",
    "services": [
      { "type": "postgresql" },
      { "type": "redis" }
    ]
  }
}

NEXUS AI clones the repo, builds the image, generates the Compose file, and brings everything up in one job.

Connecting to the database from your app

Auto-injected environment variables

When NEXUS AI provisions a database service, it injects connection variables into every container in the stack automatically. You do not configure these. Read them from process.env (Node.js), os.environ (Python), or however your framework reads environment variables.

PostgreSQL

POSTGRES_HOST      postgresql
POSTGRES_PORT      5432
POSTGRES_DB        appdb
POSTGRES_USER      appuser
POSTGRES_PASSWORD  <generated>

Node.js example:

const { Pool } = require('pg');

const pool = new Pool({
  host: process.env.POSTGRES_HOST,
  port: parseInt(process.env.POSTGRES_PORT),
  database: process.env.POSTGRES_DB,
  user: process.env.POSTGRES_USER,
  password: process.env.POSTGRES_PASSWORD,
});

Prisma .env:

DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}

Or inline in schema.prisma:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

MySQL

MYSQL_HOST      mysql
MYSQL_PORT      3306
MYSQL_DATABASE  appdb
MYSQL_USER      appuser
MYSQL_PASSWORD  <generated>

Node.js example:

const mysql = require('mysql2/promise');

const pool = mysql.createPool({
  host: process.env.MYSQL_HOST,
  port: parseInt(process.env.MYSQL_PORT),
  database: process.env.MYSQL_DATABASE,
  user: process.env.MYSQL_USER,
  password: process.env.MYSQL_PASSWORD,
});

MongoDB

MONGO_HOST      mongodb
MONGO_PORT      27017
MONGO_DATABASE  appdb
MONGO_USERNAME  root
MONGO_PASSWORD  <generated>

Mongoose example:

const mongoose = require('mongoose');

mongoose.connect(
  `mongodb://${process.env.MONGO_USERNAME}:${process.env.MONGO_PASSWORD}` +
  `@${process.env.MONGO_HOST}:${process.env.MONGO_PORT}/${process.env.MONGO_DATABASE}`
);

Redis

REDIS_HOST  redis
REDIS_PORT  6379

ioredis example:

const Redis = require('ioredis');

const redis = new Redis({
  host: process.env.REDIS_HOST,
  port: parseInt(process.env.REDIS_PORT),
});

The host in every case is the service name on the internal Docker network. From inside your container, postgresql resolves to the Postgres container, mysql to MySQL, and so on. These hostnames are not reachable from outside the deployment.

Using the secrets vault for external databases

If you connect to a database that runs outside NEXUS AI (a managed RDS instance, a MongoDB Atlas cluster, a Redis Cloud endpoint), use the secrets vault instead of hardcoding credentials.

Step 1: Create a secret

nexus secret create \
  --name DATABASE_URL \
  --value "postgresql://user:password@rds.amazonaws.com:5432/mydb" \
  --environment production

Step 2: Link it to your deployment

Pass the secret name when deploying:

nexus deploy source https://github.com/your/repo \
  --name my-app \
  --secret-ids <secret-id>

At deploy time, NEXUS AI decrypts the secret (AES-256-GCM) and injects it as an environment variable into the container. Secrets do not override variables you pass explicitly in --env. The lookup order is: explicit env vars first, then secrets.

Your application reads process.env.DATABASE_URL exactly as it would for any other environment variable. There is nothing special to configure in your code.

Rotating a secret

nexus secret update --id <secret-id> --value "new-connection-string"
nexus deploy redeploy <deployment-name>

The new value takes effect on the next deploy.

Frontend deployment

NEXUS AI Docker deployments run a single application container (plus database sidecar services). There is no built-in multi-container split for frontend and backend today.

Two patterns work:

Pattern 1: Serve the frontend from the backend

Build your frontend and serve the static files from your backend server. This is the simplest approach and fits most full-stack frameworks:

Next.js — runs as a single Node.js server (next start) that handles both SSR and API routes
Express + React — build the React app into dist/, then serve it with express.static
Django + Vue — run npm run build in your Dockerfile, copy dist/ into Django's static files directory

Your Dockerfile handles the build:

FROM node:20-alpine AS frontend-build
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ ./
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY backend/package*.json ./
RUN npm ci --production
COPY backend/ ./
COPY --from=frontend-build /app/frontend/dist ./public
EXPOSE 3000
CMD ["node", "src/index.js"]

Pattern 2: Deploy frontend separately

Deploy the frontend as a separate NEXUS AI deployment (static site or Node.js server), and point it at the backend's public URL. Use nexus deploy status <backend-name> to get the backend URL, then pass it as an environment variable to the frontend deployment.

# Get backend URL
BACKEND_URL=$(nexus deploy status my-api --json | jq -r '.url')

# Deploy frontend pointing at backend
nexus deploy source https://github.com/your/repo \
  --name my-frontend \
  --env VITE_API_URL=$BACKEND_URL

What gets deployed

After nexus deploy source completes with a database service, you get:

Your application container running on a public NEXUS AI subdomain
One or more database containers on a private internal network
Named volumes for each database (data persists across redeploys)
Auto-generated credentials injected as environment variables
Health checks configured and active
A lastBackup field ready for daily automated backups (see the backup guide)

Run nexus deploy status <name> to see the full picture: URL, status, attached services, and their connection metadata.

Database Backup and Restore in NEXUS AI: A Complete Guide

Saif Ali — Sun, 09 Aug 2026 13:13:04 +0000

Every production deployment needs a data recovery plan. NEXUS AI ships built-in backup and restore for all four supported database engines: PostgreSQL, MySQL, MongoDB, and Redis. This guide covers three ways to use it: the dashboard, the CLI, and direct API calls.

What gets backed up

When you deploy a full-stack application on NEXUS AI with a database service, the platform manages the database container alongside your app in a private Docker network. Backups capture a consistent snapshot of that data:

PostgreSQL — uses pg_dump in custom format (.dump)
MySQL — uses mysqldump SQL export (.sql)
MongoDB — uses mongodump compressed archive (.archive)
Redis — uses the native RDB snapshot (.rdb)

All backup files are stored server-side and tracked in the NEXUS AI platform. Each backup record shows the engine type, file size, status, and creation time.

Using the CLI

Install or update the CLI:

npm install -g nexusapp-cli
nexus --version

Create a backup

nexus db backup <service-id>

The command streams progress and prints a summary when done:

✔ Backup created
  ID:      3f8a1c2d-...
  Type:    postgresql
  Size:    4.2 MB
  Created: just now

Find your service-id by running nexus deploy status <deployment-name> and looking at the attached services table.

List backups

nexus db backups <service-id>

Output:

ID                                    TYPE          SIZE      STATUS     CREATED
3f8a1c2d-...                          postgresql    4.2 MB    completed  2m ago
1a2b3c4e-...                          postgresql    3.9 MB    completed  1d ago

Restore from a backup

nexus db restore <service-id> <backup-id>

You will be prompted to confirm before the restore runs — this overwrites current data. Use --yes to skip the prompt in scripts:

nexus db restore <service-id> <backup-id> --yes

Restoring PostgreSQL and MySQL replays all data with --clean / --drop semantics so the target schema is wiped before the restore. MongoDB uses --drop per collection. Redis stops the container, swaps the RDB file, and restarts — expect a few seconds of downtime.

Delete a backup

nexus db backup-delete <service-id> <backup-id>

This removes both the file on disk and the tracking record. Deletion is permanent.

Enable daily automated backups

nexus db backup-schedule <service-id> --enable

Once enabled, NEXUS AI runs a backup every 24 hours automatically. To disable:

nexus db backup-schedule <service-id> --disable

Using the REST API

All backup operations are also available over HTTP. Authenticate with a Bearer token from nexus auth token create.

Create a backup

curl -X POST https://nexusai.run/api/deployment-services/<service-id>/backup \
  -H "Authorization: Bearer $NEXUS_TOKEN"

List backups

curl https://nexusai.run/api/deployment-services/<service-id>/backups \
  -H "Authorization: Bearer $NEXUS_TOKEN"

Restore

curl -X POST https://nexusai.run/api/deployment-services/<service-id>/restore \
  -H "Authorization: Bearer $NEXUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"backupId":"<backup-id>"}'

Toggle scheduled backups

curl -X PATCH https://nexusai.run/api/deployment-services/<service-id>/backup/schedule \
  -H "Authorization: Bearer $NEXUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Disaster recovery playbook

Here is a practical runbook for restoring after data loss:

1. List your recent backups

nexus db backups <service-id> --json | jq '.[0:3]'

Pick the most recent backup with "status": "completed".

2. Verify the backup exists

nexus db backups <service-id> | grep <backup-id>

3. Run the restore

nexus db restore <service-id> <backup-id> --yes

4. Verify your application

Check your app is healthy after the restore:

nexus deploy status <deployment-name>

Watch for the health check to return healthy before routing traffic back.

Setting up automated backups (recommended)

For any production database, enable daily backups immediately after deploy:

# Deploy your app
nexus deploy source https://github.com/your/repo --name my-app

# Find the database service ID
nexus deploy status my-app --json | jq '.services[] | select(.serviceType == "postgresql") | .id'

# Enable daily backups
nexus db backup-schedule <service-id> --enable

NEXUS AI runs the backup job every 24 hours. The last backup time is visible in nexus deploy status.

What to do before a risky migration

Run a manual backup before any schema migration or destructive operation:

nexus db backup <service-id>

Save the backup ID, run your migration, and restore from that ID if anything goes wrong. This gives you a clean rollback path without downtime planning.

Engine-specific notes

PostgreSQL
Backups use pg_dump -F c (custom format). Restores use pg_restore --clean --if-exists, which drops and recreates all objects. The target database must exist.

MySQL
Backups are plain SQL dumps. Restores pipe the SQL directly into mysql. All tables in the target database are replaced.

MongoDB
Backups use mongodump with authentication against the admin database. Restores use mongorestore --drop, which removes each existing collection before importing. Only the named database is restored.

Redis
Redis backups trigger a BGSAVE and copy the resulting dump.rdb file. Restores stop the container, replace the RDB, and restart. There is a brief connection interruption during restore.

Limitations

Backup files are stored on the NEXUS AI server. For off-site copies, download them via the dashboard or export endpoints.
Backups reflect the state at the moment pg_dump / mysqldump / mongodump runs. In-flight transactions may not be captured.
Redis BGSAVE is non-blocking but the saved RDB may be up to a few seconds behind the latest write.
Restoring to a different service ID or engine type is not supported. Restore targets the same container the backup came from.

Stop shipping secrets. Start using a vault.

Saif Ali — Sun, 09 Aug 2026 13:08:37 +0000

Stop shipping secrets. Start using a vault.

Published: April 21, 2026

Category: Security · DevOps

Reading time: 12 minutes

Author: NEXUS AI Team

Leaked API keys cost companies an average of $1.2M per incident. Not because engineers are careless — because the tooling makes the wrong thing easy. .env files committed to repos. Hardcoded credentials baked into container images. Production secrets copy-pasted into Slack for "temporary" handoffs that last six months.

NEXUS AI ships a built-in Secrets Vault and a first-class Access Token system. This post covers exactly how both work, how they integrate at deploy time, and how to run a zero-plaintext secret configuration in your production environment — starting today.

The problem with secrets in 2026

Most teams manage secrets in one of three ways:

Approach	What goes wrong
`.env` files in repos	One `git log` away from a breach. "Secret" scans never catch everything.
CI/CD environment variables	Visible to anyone with repo access. Rotate one and you're editing 14 pipelines.
Cloud secret managers (AWS Secrets Manager, GCP Secret Manager)	Right idea, wrong integration. Requires service accounts, IAM glue, and a custom fetch layer in every app.

The common thread: secrets live somewhere they shouldn't, accessed by code that has more permission than it needs, with no record of who read what.

NEXUS AI eliminates all three failure modes at the platform level.

The NEXUS AI Secrets Vault

Every NEXUS AI project ships with an encrypted Secrets Vault. Secrets are encrypted at rest using AES-256-GCM before they touch the database — the same cipher used by the U.S. Department of Defense for classified data at rest.

How encryption works

When you store a secret, NEXUS AI:

Encrypts the value with AES-256-GCM using a derived key (scoped per organization).
Stores only the ciphertext, the IV (initialization vector), and the auth tag.
Never writes the plaintext to disk, logs, or any observable surface.

The encryption key itself is never stored alongside the ciphertext. It's derived at runtime from SECRETS_ENCRYPTION_KEY — an environment variable you set once at the platform level and never touch again.

# Set via the NEXUS AI CLI
nexus secret set DATABASE_URL "postgres://user:pass@host:5432/db"
nexus secret set STRIPE_SECRET_KEY "sk_live_..."
nexus secret set OPENAI_API_KEY "sk-..."

Secrets are namespaced per deployment. A secret set for api-prod is not visible to api-staging — even if both deployments live in the same project.

What the vault does NOT do

No system is better described by its constraints than its capabilities:

The vault does not store secrets in application containers. Secrets are injected at runtime as environment variables, never embedded in the image.
The vault does not expose secret values through logs. The observability pipeline redacts known secret patterns automatically.
The vault does not allow cross-tenant secret access. Secrets are scoped to an organization ID enforced at the query layer — not just the API layer.

Secure Configuration Injection

When NEXUS AI deploys your application, secrets don't get "loaded" by your app at startup. They're injected into the container's environment by the runtime before the first process starts.

The sequence:

1. Deploy command issued
2. NEXUS AI fetches encrypted secrets for the target deployment
3. Secrets decrypted in the control plane (never on the container host)
4. Injected as environment variables into the container spec
5. Container starts — secrets already present as env vars
6. Plaintext exists only in memory, for the lifetime of the process

Your application code reads process.env.DATABASE_URL exactly as it always has. Zero changes to application code. Zero additional SDK imports. Zero IAM role configuration.

This is what NEXUS AI calls Secure Configuration Injection — vault-backed runtime config by default.

Access Tokens

Secrets protect your application's config. Access Tokens protect access to NEXUS AI itself.

An Access Token is a scoped credential that authenticates API calls to NEXUS AI — including calls from the CLI, CI/CD pipelines, external scripts, or AI agents running via MCP.

Token anatomy

Every NEXUS AI Access Token carries three pieces of information:

Field	Purpose
`token_id`	Stable identifier. Visible in audit logs. Safe to display.
`token_value`	The actual secret. Shown once at creation. Never stored in plaintext.
`scopes`	What the token is allowed to do. Read-only? Deploy-only? Full control?

Tokens are hashed with SHA-256 before storage. If an attacker gets your database, they get hashes — not tokens.

Creating a token

# CLI
nexus token create --name "ci-deploy-prod" --scopes deploy:write,secrets:read

# Output:
# Token ID:    tok_01HX9...
# Token value: nxt_live_...  ← shown once, copy it now
# Scopes:      deploy:write, secrets:read
# Expires:     never (set --expires 90d to add expiry)

# Or via the NEXUS AI dashboard:
# Settings → Access Tokens → New Token

For CI/CD pipelines, store the token value as a repository secret in your provider (GitHub Actions, GitLab CI, etc.) and inject it as NEXUS_API_KEY.

Token scopes

NEXUS AI uses a least-privilege scope model. Grant exactly what the caller needs — nothing more.

Scope	What it allows
`deploy:read`	View deployment status, logs, metadata
`deploy:write`	Create, redeploy, rollback, stop deployments
`secrets:read`	List secret names (never values)
`secrets:write`	Create, update, delete secrets
`billing:read`	View usage and invoices
`admin`	Full organization access

A CI/CD pipeline that only needs to redeploy on merge gets deploy:write. It cannot read secrets, cannot view billing, cannot create new deployments from scratch. One compromised pipeline token does not become a full organization breach.

Token expiry and rotation

Short-lived tokens are better tokens. Set expiry explicitly:

nexus token create --name "github-actions-main" --scopes deploy:write --expires 90d

Rotate before expiry:

nexus token rotate tok_01HX9...
# Old token: revoked immediately
# New token: nxt_live_...  ← 90-day window restarts

Rotation is zero-downtime. The old token stays valid for a 5-minute grace window — long enough for an in-flight deploy to complete, short enough that a leaked token has minimal exposure.

Secrets + Tokens in a real pipeline

Here's what a production-grade deploy pipeline looks like with NEXUS AI:

Step 1: Store secrets once

# Done once, by a developer with secrets:write scope
nexus secret set DATABASE_URL "$DATABASE_URL"
nexus secret set REDIS_URL "$REDIS_URL"
nexus secret set JWT_SECRET "$(openssl rand -hex 32)"

Step 2: Create a scoped CI token

# Create a deploy-only token for GitHub Actions
nexus token create --name "github-actions-main" --scopes deploy:write --expires 90d
# → Store the token value in GitHub Actions secrets as NEXUS_API_KEY

Step 3: CI/CD pipeline (GitHub Actions example)

name: Deploy to production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to NEXUS AI
        env:
          NEXUS_API_KEY: ${{ secrets.NEXUS_API_KEY }}
        run: |
          npx nexus-cli deploy redeploy --deployment api-prod

No secrets in the pipeline YAML. No secrets in the container image. The pipeline token can trigger a redeploy — it cannot read DATABASE_URL, cannot change secrets, cannot touch other projects.

Step 4: Runtime

When the container starts, it finds:

DATABASE_URL=postgres://...
REDIS_URL=redis://...
JWT_SECRET=...

Ready. No SDK. No fetch-on-startup. No cold-start latency penalty from secret retrieval.

RBAC and the audit trail

Access Tokens operate within NEXUS AI's Role-Based Access Control (RBAC) system. Every token is issued to an organization member with a role:

Role	What they can do
Viewer	Read logs, status, and deployment metadata
Developer	Deploy, redeploy, rollback; read secret names
Admin	Full control including secrets, tokens, and billing
Owner	Everything Admin can do + delete the organization

A Developer role member creating a token cannot grant that token admin scope. Privilege escalation via token creation is blocked at the model layer.

The audit log

Every secret operation and token use is recorded:

{
  "event": "secret.updated",
  "actor": "saif@example.com",
  "token_id": null,
  "target": "DATABASE_URL",
  "deployment": "api-prod",
  "timestamp": "2026-04-21T09:14:22Z",
  "ip": "203.0.113.45"
}

{
  "event": "deploy.redeploy",
  "actor": null,
  "token_id": "tok_01HX9...",
  "target": "api-prod",
  "deployment": "api-prod",
  "timestamp": "2026-04-21T09:17:05Z",
  "ip": "140.82.114.3"
}

When a deploy fires at 3 AM, you know it was the CI token. When a secret changes, you know who changed it and from where. Audit logs are append-only, exported to your observability stack, and retained for 90 days on Pro and indefinitely on Enterprise.

MCP: AI agents and your secrets vault

NEXUS AI ships 37 MCP tools for Claude and other AI agents. When an AI agent uses a token to call the NEXUS AI MCP server, it operates under the same scope model as a human caller.

An agent with deploy:read can inspect deployment status and fetch logs. It cannot modify secrets, redeploy, or rollback — unless its token includes deploy:write.

# Agent calls nexusai_deploy_status → allowed (deploy:read)
# Agent calls nexusai_secrets_create → blocked (secrets:write not granted)
# Agent calls nexusai_deploy_redeploy → blocked (deploy:write not granted)

This means you can give Claude read-only access to your production environment for diagnosis — and be certain it cannot modify anything. When you want Claude to act (redeploy, rollback), you issue a deploy:write token explicitly, scoped to exactly that.

AI agents with unconstrained production access are a liability. Scoped tokens make AI-assisted operations safe by default.

Checklist: zero-plaintext secrets in 10 minutes

[ ] Store all secrets with nexus secret set — delete any existing .env from your repo
[ ] Create deployment-scoped tokens for every CI/CD pipeline — one token per pipeline
[ ] Set token expiry to 90 days maximum — calendar reminders for rotation
[ ] Assign team members the minimum role they need — Viewers don't need Developer
[ ] Enable audit log export to your SIEM or logging stack (Datadog, Grafana, etc.)
[ ] Run nexus secret list quarterly — delete secrets that no longer have a deployment

Frequently asked questions

Can I view a secret value after I've stored it?

No. The vault stores only the encrypted ciphertext. The plaintext value is shown once at creation. This is intentional — if you need to verify a secret, rotate it.

What happens to secrets if I delete a deployment?

Secrets are scoped to a deployment. Deleting the deployment marks its secrets as orphaned. Orphaned secrets are purged automatically after 30 days, or immediately if you run nexus secret purge --deployment <name>.

How do I handle secrets that multiple deployments share?

Set the secret on each deployment. NEXUS AI does not support cross-deployment secret references by design — shared access is shared blast radius. Duplication is cheaper than a cross-project breach.

Can a Developer-role member read secret values?

No. secrets:read scope lists secret names (e.g., DATABASE_URL) but never values. Only the NEXUS AI control plane decrypts values — and only at deploy time, into the container environment.

What encryption key does NEXUS AI use?

On NEXUS AI-managed infrastructure, the encryption key is managed by the platform and rotated automatically. On Enterprise On-Prem, you supply SECRETS_ENCRYPTION_KEY and own the key lifecycle entirely.

Can I use NEXUS AI secrets with a non-NEXUS AI host?

Not directly. The vault is tightly integrated with the deployment runtime. If you're running on external infrastructure, use your cloud provider's native secret manager and inject credentials at the infrastructure level.

What's next

Secrets Vault and Access Tokens ship on every NEXUS AI plan — including Starter at $29/mo. No additional configuration, no third-party integrations, no IAM policy documents.

If you're on an Enterprise or regulated workload, RBAC, audit log retention, and on-prem key management are available on Enterprise and Enterprise On-Prem tiers. Talk to the team at nexusai.run.

Related reading:

How NEXUS AI deploys your app in under 5 minutes
RBAC deep dive: roles, scopes, and least privilege
MCP integration: 37 tools for Claude and AI agents
Audit logs and compliance: what gets recorded and why

Ship what matters. Lock down the rest.

From v0 prototype to production database in 5 minutes

Saif Ali — Sun, 09 Aug 2026 13:05:36 +0000

From v0 prototype to production database in 5 minutes

Published: May 17, 2026
Category: AI · Next.js · Databases
Reading time: 8 minutes
Author: NEXUS AI Team

v0 by Vercel generates a beautiful React component in 60 seconds. Lovable, Bolt, and Replit do the same for whole frontends. The result looks production-ready in the browser.

Then you try to save a user. There is no database. There is no auth backend. There is no file storage. The "deploy" button shipped a frontend with a fetch call pointed at a URL that does not exist yet.

This is the deploy gap for prototyping tools, and it is where most teams either give up or end up wiring three SaaS dashboards together. This post shows the third path: take the v0 prototype, give it a real Postgres backend, attach a bucket for uploads, and have the whole stack running in about 5 minutes.

For the broader picture of why AI-generated apps need a different deploy story, see Your AI app is generated. Now how do you deploy it?.

What v0 (and friends) actually ship

The current generation of AI prototyping tools ship a Next.js frontend with hard-coded data, or wire it to a serverless route file with mock responses. You can run it locally. You can deploy the frontend to Vercel. What you do not get out of the box:

A managed database with persistence (Postgres, MySQL, Mongo).
An object store for image uploads, model artifacts, or generated assets.
A background worker for async tasks.
Secrets management for API keys.
Backups and a restore path.
Logs you can stream.

For a real app you need all of these. For an AI-built side project you usually need at least the first two.

Three ways to add a real backend

Vercel Postgres + Vercel KV. Convenient if your frontend is already on Vercel. Adds a second billing line, a separate IAM model, and locks the data to Vercel's region story. No background workers.

Bring-your-own Supabase, Neon, or PlanetScale. Best-in-class managed databases. You still own the wiring between the database, your frontend, your storage provider (separate again), your queue provider (separate again), and your secrets vault. Three dashboards minimum, sometimes five.

NEXUS AI. One deploy gives you a containerized backend, a managed Postgres, optional Redis, an S3-compatible bucket, encrypted secrets, backups, scaling, and a public URL. One dashboard. One CLI. One MCP server your AI agent can drive end-to-end.

This post walks through the third path because the others are well documented elsewhere.

Step 1: export the v0 frontend

v0 already supports Add to codebase. Push the result to a GitHub repo. The frontend will look something like:

my-v0-app/
  app/
    layout.tsx
    page.tsx
    api/
      users/
        route.ts        ← currently returns mock data
      uploads/
        route.ts        ← currently returns a fake URL
  package.json
  next.config.js

The two route files are where we replace the mocks. We will leave them in the same Next.js app rather than building a separate Express backend. v0 + Next.js + Postgres + S3 is a complete production stack on its own.

Step 2: wire the route handlers to real services

Update app/api/users/route.ts to talk to Postgres:

import { NextResponse } from "next/server";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function GET() {
  const { rows } = await pool.query(
    "SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 50"
  );
  return NextResponse.json(rows);
}

export async function POST(req: Request) {
  const { email } = await req.json();
  const { rows } = await pool.query(
    "INSERT INTO users (email) VALUES ($1) RETURNING id, email, created_at",
    [email]
  );
  return NextResponse.json(rows[0]);
}

Update app/api/uploads/route.ts to push to the S3-compatible bucket NEXUS AI provisions:

import { NextResponse } from "next/server";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { randomUUID } from "crypto";

const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  region: process.env.S3_REGION || "us-east-1",
  forcePathStyle: true,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY!,
    secretAccessKey: process.env.S3_SECRET_KEY!,
  },
});

export async function POST(req: Request) {
  const form = await req.formData();
  const file = form.get("file") as File;
  const key = `${randomUUID()}-${file.name}`;
  const body = Buffer.from(await file.arrayBuffer());

  await s3.send(
    new PutObjectCommand({
      Bucket: process.env.S3_BUCKET!,
      Key: key,
      Body: body,
      ContentType: file.type,
    })
  );

  return NextResponse.json({ key, url: `${process.env.S3_ENDPOINT}/${process.env.S3_BUCKET}/${key}` });
}

Add a tiny migration that creates the users table. Put it in db/init.sql:

CREATE TABLE IF NOT EXISTS users (
  id          serial PRIMARY KEY,
  email       text NOT NULL UNIQUE,
  created_at  timestamptz NOT NULL DEFAULT now()
);

Commit and push.

Step 3: deploy the whole stack with one command

Install the NEXUS AI CLI:

curl -fsSL https://nexusai.run/install.sh | bash    # Linux
curl -fsSL https://nexusai.run/install-mac.sh | bash # macOS
nexus auth login

Deploy the app, Postgres, and a bucket:

nexus deploy source \
  --repo https://github.com/you/my-v0-app.git \
  --name my-v0-app \
  --provider docker \
  --framework nextjs \
  --services postgresql \
  --wait

Create and attach a bucket for uploads:

nexus bucket create user-uploads --display-name "User uploads"
nexus bucket attach <bucket-id> <deployment-id>
nexus deploy redeploy <deployment-id> --wait

The platform builds the Next.js production image, provisions a Postgres 15 container with a persistent volume, generates a scoped per-bucket IAM service account, injects the environment variables (DATABASE_URL, S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY), opens a public HTTPS URL through Traefik, and starts streaming logs.

Run the schema migration:

nexus db query <postgres-service-id> --file db/init.sql

Step 4: verify the full path

Hit the deployed URL:

curl -X POST https://your-app.nexusai.run/api/users \
  -H "Content-Type: application/json" \
  -d '{"email":"first@example.com"}'

curl https://your-app.nexusai.run/api/users

Expected response on the GET:

[
  {
    "id": 1,
    "email": "first@example.com",
    "created_at": "2026-05-17T03:14:22.117Z"
  }
]

Upload a file:

curl -X POST https://your-app.nexusai.run/api/uploads \
  -F "file=@./avatar.png"

Expected response:

{
  "key": "9b4e2a01-avatar.png",
  "url": "https://minio.nexusai.run/user-uploads/9b4e2a01-avatar.png"
}

You now have a v0-generated frontend talking to a real Postgres and a real S3 bucket. No third dashboard.

Step 5: take the first backup

The first ops habit worth installing on day one is backups. Take a snapshot:

nexus db services my-v0-app
nexus db backup <postgres-service-id>
nexus db backups <postgres-service-id>

Schedule recurring backups:

nexus db backup-schedule <postgres-service-id> --cron "0 3 * * *"  # daily at 3am UTC

Backups are encrypted, retained per your plan limits, and downloadable on demand:

nexus db backup-download <postgres-service-id> <backup-id> --out ./dump.sql

Or share with a teammate via a signed URL with a 30-second to 1-hour TTL:

nexus db backup-download <postgres-service-id> <backup-id> --share --ttl 600

Step 6: scale when the prototype takes off

The day the post hits the front page of Hacker News:

nexus deploy scale my-v0-app 5

The Next.js app scales to 5 replicas behind the load balancer. Postgres and the bucket stay as the single source of truth for state. The frontend layer is stateless, so scaling horizontally is safe.

When traffic dies down:

nexus deploy scale my-v0-app 1

Why one platform instead of three

Every additional vendor in the path between your code and your data adds three costs you do not see on day one:

Operational tax. Each dashboard needs a login, a billing setup, an IAM model, and a backup story. Each is a place a breach or an expired credit card can stop your app.
Latency. Database in one region, object store in another, frontend on edge: each network hop is real milliseconds on every request.
Recovery surface. When something breaks you debug across vendor boundaries. Slack threads with five companies' support teams resolve slower than one ticket with one provider.

Consolidating the backend into one platform does not preempt best-of-breed choices later. You can run NEXUS AI as the prototype platform and migrate the database to a dedicated provider after product-market fit. nexus db backup-download gives you a portable Postgres dump whenever you want to leave.

Patterns that scale beyond v0

The same pattern works for Lovable, Bolt, Replit, and any framework v0 supports:

Lovable. Push the Lovable export to GitHub, deploy with --framework nextjs or --framework vite, attach Postgres and a bucket.
Bolt.new. Same flow. Bolt generates standalone Next.js or Vite projects.
Replit. Connect your Replit GitHub mirror, deploy with the appropriate framework flag.
Claude Code or Cursor generated apps. Direct push, direct deploy. Claude Code can also call the NEXUS AI MCP tools and deploy itself (see MCP-driven deploys).

The deploy command stays the same. The only thing that changes is the framework flag.

FAQ

Does v0 work with NEXUS AI directly?
v0 generates a Next.js project. NEXUS AI deploys Next.js projects from any Git repository. There is no special integration required. Push to GitHub, run nexus deploy source --framework nextjs.

Do I need to write a Dockerfile?
No. NEXUS AI detects Next.js and generates a multi-stage production Dockerfile (build with npm run build, run with node server.js or next start as appropriate).

Can I keep my frontend on Vercel and put only the backend on NEXUS AI?
Yes. Deploy just an API service (nexus deploy source --framework express for a standalone Express backend, or a Next.js app with only app/api/ routes used). Point your Vercel frontend at the NEXUS AI URL via NEXT_PUBLIC_API_URL. You get Vercel's CDN and NEXUS AI's stateful backend.

Does Postgres survive container restarts?
Yes. The Postgres data lives on a persistent volume attached to the deployment. Volumes survive container restarts, redeploys, and host reboots. See How NEXUS AI keeps your Postgres alive across host reboots for the implementation details.

What about authentication?
NEXUS AI does not ship a managed auth provider. Use Auth.js (NextAuth), Clerk, or Supabase Auth from your Next.js app. The auth provider stores session state in your NEXUS AI Postgres or Redis service.

Can my AI agent run all of this for me?
Yes. Connect the NEXUS AI MCP server to Claude Code, Cursor, or another MCP client. The agent calls nexusai_deploy_source, nexusai_bucket_create, nexusai_bucket_attach, and nexusai_db_query to do everything in this post end-to-end. See MCP-driven deploys for the 60-second setup.

The deploy gap from v0 prototype to production app used to be the bottleneck. With one CLI command and one platform it collapses to about 5 minutes.

Start free.

Database service backups in NEXUS AI

Saif Ali — Sun, 09 Aug 2026 13:02:03 +0000

Database service backups in NEXUS AI: backup, in-place restore, and cross-service restore

Published: May 9, 2026

Category: Databases · DevOps

Reading time: 10 minutes

Author: NEXUS AI Team

Database backups should be boring. You should be able to create one, download it, restore it into the same service, or restore it into a replacement deployment without rebuilding the whole application stack by hand.

NEXUS AI database services now support that full lifecycle for deployment-attached database services. You can back up PostgreSQL, MySQL, MongoDB, and Redis services, restore a backup back into the original service, or restore it into another compatible database service in a different deployment under the same organization.

This post walks through the complete workflow using the dashboard, REST API, CLI, and MCP tools.

What database backups cover

NEXUS AI backups are created from database services attached to a deployment through Additional Services.

Supported engines:

Service	Backup format	Restore behavior
PostgreSQL	`pg_dump` custom dump	Restores database objects with clean/replace behavior
MySQL	SQL dump	Imports the dump into the target database
MongoDB	compressed `mongodump` archive	Restores collections with drop behavior
Redis	RDB snapshot	Replaces the target Redis dataset

Backups are organization-scoped. A backup created in one organization cannot be restored into another organization. Cross-service restore is allowed only when the target service belongs to the same organization and uses a compatible database engine.

Backups do not include application code, container images, secrets, deployment configuration, or filesystem volumes. They cover the database service data only.

Create a database backup

First, find the database service you want to back up.

nexus db services
nexus db services <deployment-name-or-id>

Create the backup:

nexus db backup <service-id>

List backups for that service:

nexus db backups <service-id>
nexus db backups <service-id> --json

You can also create a backup through the REST API:

export NEXUS_API_BASE="https://nexusai.run/api"
export NEXUS_JWT="YOUR_JWT_FROM_LOGIN"

curl -s -X POST "$NEXUS_API_BASE/deployment-services/<serviceId>/backup" \
  -H "Authorization: Bearer $NEXUS_JWT"

NEXUS AI runs the native database backup tool inside the running database container and stores the backup record for later download or restore.

Download a backup

For local retention, migration testing, or compliance workflows, download the backup file:

nexus db backup-download <service-id> <backup-id>
nexus db backup-download <service-id> <backup-id> --out ./backups/prod-postgres.dump

To create a short-lived signed download URL:

nexus db backup-download <service-id> <backup-id> --share
nexus db backup-download <service-id> <backup-id> --share --ttl 900

The REST API supports both direct downloads and signed URLs:

curl -L -o backup.dump \
  "$NEXUS_API_BASE/deployment-services/<serviceId>/backups/<backupId>/download" \
  -H "Authorization: Bearer $NEXUS_JWT"

curl -s -X POST "$NEXUS_API_BASE/deployment-services/<serviceId>/backups/<backupId>/download-url" \
  -H "Authorization: Bearer $NEXUS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":900}'

Treat downloaded backup files as sensitive. They may contain production user data, application data, credentials stored in tables, or regulated records.

Restore into the same service

Use in-place restore when you want to roll a database service back to a known backup.

CLI:

nexus db restore <service-id> <backup-id>
nexus db restore <service-id> <backup-id> --yes

REST:

curl -s -X POST "$NEXUS_API_BASE/deployment-services/<serviceId>/restore" \
  -H "Authorization: Bearer $NEXUS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"backupId":"<backupId>"}'

Use in-place restore carefully. Restore can overwrite, clean, drop, or replace data depending on the database engine. Before restoring, create a fresh backup of the current state if you may need to roll forward again.

Recommended in-place restore workflow:

Put the app into maintenance mode or stop write-heavy workers.
Create a fresh backup of the current service.
Restore the selected backup.
Restart or redeploy application containers if they cache connections or schema metadata.
Validate critical flows before sending normal traffic back to the deployment.

Restore into another deployment service

Cross-service restore is useful when you want to restore production data into a staging deployment, migrate data to a replacement deployment, test a backup without touching the source service, or recover into a newly created database service.

The target service must be:

In the same organization as the backup.
A compatible database engine.
Running and reachable by NEXUS AI.
Safe to overwrite.

CLI:

nexus db restore-to <target-service-id> <backup-id>
nexus db restore-to <target-service-id> <backup-id> --yes
nexus db restore-to <target-service-id> <backup-id> --json

REST:

curl -s -X POST "$NEXUS_API_BASE/deployment-services/<targetServiceId>/restore-from/<backupId>" \
  -H "Authorization: Bearer $NEXUS_JWT"

MCP:

nexusai_db_restore_to

The MCP tool requires deployments:create scope. When using an AI client, include the backup ID and target service ID explicitly, then confirm the destructive operation before the tool call.

Backend integrations can call:

await backupService.restoreBackup(backupId, { targetServiceId });

The targetServiceId option is optional. Existing in-place restore calls continue to work:

await backupService.restoreBackup(backupId);

Example: restore production data into staging

This workflow copies a production database backup into a staging database service under the same organization.

# 1. Find production database service
nexus db services prod-api

# 2. Create a production backup
nexus db backup <prod-service-id>

# 3. List backups and copy the backup id
nexus db backups <prod-service-id>

# 4. Find the staging database service
nexus db services staging-api

# 5. Restore the production backup into staging
nexus db restore-to <staging-service-id> <backup-id> --yes

After restore, restart or redeploy the staging app if it caches database connections, schema state, or application-level lookup data.

nexus deploy redeploy <staging-deployment-id> --wait

Example: recover into a replacement deployment

If a deployment is being replaced, create the new deployment with the same database service type, then restore the backup into the new database service.

# Create or identify the replacement deployment
nexus deploy source \
  --repo https://github.com/your-org/your-app \
  --name api-replacement \
  --provider docker \
  --services postgresql \
  --wait

# Find the replacement PostgreSQL service
nexus db services api-replacement

# Restore the backup into the replacement service
nexus db restore-to <replacement-postgres-service-id> <backup-id> --yes

This lets you validate the replacement deployment before cutting traffic over.

Safety checklist before restore

Before any restore, confirm:

The backup ID is correct.
The target service ID is correct.
The target service belongs to the same organization.
The target service uses the same database engine.
You understand that target data may be overwritten.
You have a fresh backup of the target service if rollback matters.
Application workers are paused if they may write during restore.

For production services, schedule a maintenance window. Database restore is a data-changing operation, not a harmless read.

Common questions

Can I restore a backup into a different deployment?

Yes. Use nexus db restore-to <target-service-id> <backup-id> or POST /api/deployment-services/:targetServiceId/restore-from/:backupId. The target service must be in the same organization and compatible with the backup engine.

Can I restore across organizations?

No. Cross-organization restore is blocked. Backups and database services are organization-scoped to prevent cross-tenant data access.

Does restore overwrite existing data?

Yes. Restore can overwrite, clean, drop, or replace existing data depending on the engine. Treat every restore as destructive unless you have verified otherwise for your specific database and backup.

Does the old in-place restore endpoint still work?

Yes. Existing restore flows still work:

nexus db restore <service-id> <backup-id>

POST /api/deployment-services/:serviceId/restore

The new cross-service restore path adds a target-service restore option without removing the old behavior.

Should I use download-and-manual-restore instead?

Use built-in restore for same-org NEXUS AI database services. Use manual restore when moving data outside NEXUS AI, restoring into an external managed database, or performing a custom migration that needs database-native flags not exposed by the platform.

Final takeaway

NEXUS AI database backups are designed for the actual recovery workflows teams need:

Back up a running database service.
Download the backup for retention or audit.
Restore in place when you need rollback.
Restore into another same-org service when you need staging refreshes, migration testing, or deployment replacement.

The important rule is simple: choose the target service carefully. Restore is powerful because it changes real data.