DEV Community: Saif Ali

The best way to deploy an HTML website and API to the cloud

Saif Ali — Sat, 22 Aug 2026 18:11:14 +0000

The best way to deploy an HTML website and API to the cloud

Published: August 10, 2026
Category: Deployments · Fundamentals
Reading time: 6 minutes
Author: NEXUS AI Team

Short answer: if your HTML and your API are small enough to ship together, put them in one server (a static folder plus a few routes) and deploy that as a single container. It is one URL, no CORS, no second bill, and it fits on a free tier. Split them into two separately-hosted services only when you actually need independent scaling or a different tech stack for each side. This post covers both paths, with the commands for each.

The three ways people actually do this

1. One server, two jobs. An Express, FastAPI, or Flask app that serves your index.html (and any CSS/JS) as static files from one route, and your API as JSON routes on the same port. One deploy, one URL, one process. This is the right default for a portfolio site, an internal tool, a small SaaS MVP, or anything where the frontend and backend ship together.

2. Two hosts, one app. The HTML lives on a static host (a CDN edge network), the API lives on a separate compute host, and the frontend calls the API's URL over HTTPS with CORS enabled. This is the classic Vercel/Netlify-plus-Render/Railway pattern. It buys you independent scaling and a CDN for the static assets, at the cost of two dashboards, two bills, and a CORS config to maintain.

3. Raw cloud primitives. S3 or Cloud Storage plus a CDN in front for the HTML, then Lambda/Cloud Functions or a VM for the API. Full control, the most setup work, and you own the plumbing (TLS certs, IAM, deploy scripts) yourself.

Most people asking "what's the best way to deploy my HTML site and API" have something closer to option 1 in mind and don't need the operational overhead of options 2 or 3 yet.

	Setup time	Cost to start	Scaling	Best for
One server, two jobs	~5 minutes	Free tier fits	Vertical, then horizontal	MVPs, internal tools, small apps
Two hosts, one app	~15–30 minutes	Two free tiers, or one paid	Independent per side	Apps that outgrew #1
Raw cloud primitives	Hours to days	Pay-as-you-go	Fully manual	Teams with existing cloud infra

Option 1: deploy HTML + API together as one container

This is the fastest path and the one this section walks through end to end using NEXUS AI, which auto-detects a static folder next to an API server and builds a single production Dockerfile for it — no Dockerfile required on your side.

Project layout

my-app/
  public/
    index.html
    style.css
    app.js
  server.js        ← serves /public and the /api routes
  package.json

// server.js
const express = require("express");
const path = require("path");
const app = express();

app.use(express.static(path.join(__dirname, "public")));
app.use(express.json());

app.get("/api/health", (req, res) => res.json({ status: "ok" }));

app.get("/api/items", (req, res) => {
  res.json([{ id: 1, name: "First item" }]);
});

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`Listening on ${port}`));

Deploy it

Install the CLI and log in:

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

Push the repo to GitHub, then deploy:

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

NEXUS AI builds a production image, opens a public HTTPS URL through Traefik, and streams build logs while it works. When it finishes, https://my-app.nexusai.run serves the HTML at / and JSON at /api/* from the same origin. No CORS headers needed because it is one origin.

If your HTML has no server logic at all (pure static, no API in the same process), skip the Express wrapper and deploy the folder directly:

nexus deploy source \
  --repo https://github.com/you/my-static-site.git \
  --name my-static-site \
  --provider docker \
  --framework static \
  --wait

NEXUS AI detects the plain index.html and serves it with nginx.

Add environment variables and a custom domain

nexus secret create DATABASE_URL "postgres://..." --project my-app
nexus domain add my-app yourdomain.com
nexus domain verify my-app <domain-id>

That covers the common case: one small app, one deploy, one bill, free tier eligible.

Option 2: split the static site and the API into two services

Reach for this once the frontend and backend genuinely need to scale, deploy, or fail independently — a marketing site that gets Hacker-News-front-page traffic spikes while the API stays flat, or a frontend team shipping on a different cadence than the backend team.

Deploy the API on its own:

nexus deploy source \
  --repo https://github.com/you/my-api.git \
  --name my-api \
  --provider docker \
  --framework express \
  --wait

Deploy the static HTML as a second service in the same project (this needs a plan with more than one active deployment — see the FAQ below):

nexus deploy source \
  --repo https://github.com/you/my-frontend.git \
  --name my-frontend \
  --provider docker \
  --framework static \
  --wait

Point the frontend's fetch calls at the API's public URL, and enable CORS on the API for the frontend's origin:

// my-api/server.js
const cors = require("cors");
app.use(cors({ origin: "https://my-frontend.nexusai.run" }));

// my-frontend/app.js
fetch("https://my-api.nexusai.run/api/items")
  .then((r) => r.json())
  .then(render);

Each service now scales, redeploys, and rolls back independently:

nexus deploy scale my-api 3

You can also mix providers here: keep the static frontend on a CDN-first host (Vercel, Netlify, GitHub Pages) for free and put only the API on NEXUS AI. Point the frontend's NEXT_PUBLIC_API_URL (or equivalent) at the NEXUS AI URL and enable CORS the same way.

FAQ

Do I need to write a Dockerfile for a plain HTML site?
No. NEXUS AI detects an index.html with no build manifest and serves it with nginx automatically. If you have a build step (Vite, React, Vue), it detects the framework and runs the production build instead.

My API needs a database. Does that change the deploy?
No extra service to wire up separately. Add --services postgresql (or mysql, mongodb, redis) to the same nexus deploy source command and NEXUS AI provisions the database alongside your app in the same deploy, with DATABASE_URL injected automatically.

Can I use a custom domain instead of the .nexusai.run subdomain?
Yes, on any paid plan. nexus domain add <deployment> yourdomain.com, then verify the DNS record NEXUS AI gives you.

Is there a free tier?
Yes. The Free plan includes one active deployment on the NEXUS AI managed cloud, no credit card required — enough for the single-server pattern in Option 1. Running the two-service split in Option 2 on NEXUS AI for both halves needs a plan that allows more than one active deployment (Pro and above); running just the API on NEXUS AI Free while the static frontend sits on a separate free static host works within the Free plan.

Does this handle HTTPS automatically?
Yes. Every deployment gets a public HTTPS URL through Traefik by default, and custom domains get certificates provisioned automatically once DNS verification passes.

Can I deploy from the GitHub UI instead of the CLI?
Yes. Connect your GitHub account from the NEXUS AI dashboard, select a repo and branch, and enable auto-deploy so every push to that branch redeploys automatically.

What if I'd rather describe the app in plain English and skip writing server.js myself?
Use the AI App Builder instead: describe the HTML site and the API you want in chat, review the generated files and live preview, then deploy from the same dashboard.

For an app with a real database, background workers, and file storage in addition to the HTML + API pair, see From v0 prototype to production database in 5 minutes and Deploy a full-stack Python app with Postgres, Redis, and workers in 5 minutes.

Start free.

Enterprise vibe coding: the governance framework for shipping AI-generated apps to production

Saif Ali — Sat, 22 Aug 2026 18:09:02 +0000

Enterprise vibe coding: the governance framework for shipping AI-generated apps to production

Published: August 22, 2026
Category: Enterprise · AI Deployments
Reading time: 9 minutes
Author: NEXUS AI Team

Gartner forecasts that 40% of new enterprise production software will be built using vibe coding techniques by 2028. A 2026 scan of more than 1,400 live vibe-coded applications found that 65% already had a security issue, and 58% shipped with at least one critical vulnerability. Those two numbers describe the same industry moving in opposite directions at once: adoption is outrunning governance.

This post covers what a governance framework for enterprise vibe coding actually looks like, the five controls it needs, and where most teams get it wrong.

What is enterprise vibe coding?

Enterprise vibe coding is the practice of using natural-language prompts to generate application code, then governing that code through mandatory review, access control, and audit before it reaches production, rather than letting it ship straight from a prompt to a live endpoint. The term (coined by Andrej Karpathy in early 2025) originally described a fast, low-friction way for one person to build a prototype. What "enterprise" adds is the governance layer prototyping was never built for: staging environments, encrypted secrets, role-based access, and a record of who approved what.

That distinction matters because the adoption curve and the risk curve are not moving together.

The governance gap, in three numbers

40% of new enterprise production software will be built using vibe coding techniques by 2028, according to Gartner's May 2025 report "Why Vibe Coding Needs to Be Taken Seriously," as reported by CIO Dive.
65% of vibe-coded production applications had a security issue, in a 2026 scan of more than 1,400 live apps by the API security firm Escape.tech, reported via a Cloud Security Alliance research note.
58% of those same applications shipped with at least one critical vulnerability, including hardcoded secrets and exposed personally identifiable information, per the same research note.

Enterprises are not waiting for a governance model before they start vibe coding internal tools, dashboards, and customer-facing features. They already have prototypes running in places IT never reviewed: a developer's laptop, a personal cloud account, a container nobody on the security team knows exists.

The fix is not to slow down adoption. It is to give the workflow teams already use a governed path to production, instead of asking them to abandon a workflow that is, by every account, faster than what it replaced.

What "enterprise-ready" actually requires

Most vibe coding tools are optimized for the first 90% of the problem: turning a prompt into working code fast. Enterprise readiness is almost entirely about the remaining 10%, the part that happens after the code works and before it is trusted with real users or real data.

Capability	Consumer vibe-coding tools	Enterprise-ready platform
Where it runs	Vendor-hosted, shared infrastructure	Your own AWS, Google Cloud, or Azure account
Secrets handling	Frequently hardcoded into generated code	Encrypted secrets vault, injected at runtime
Change review	Rare or none — the agent applies changes directly	Every schema and infrastructure change reviewed by a human before it ships
Access control	Single shared account, no role separation	Role-based access control (RBAC) with least-privilege defaults
Audit trail	Rare or none	Full audit log of every automated action, attributable to a user or agent
Rollback	Manual, if available at all	One-click versioned rollback
Data residency	Decided by the vendor	Decided by the customer (on-premises, private cloud, or hybrid)

None of these controls are exotic. They are the same controls that already exist for human-written code in any organization with a functioning SDLC. The gap is that most vibe coding tools were built for individual prototyping, where none of this mattered, and enterprises adopted them anyway because the alternative, a developer manually gluing infrastructure together, was slower.

A five-control governance framework

Enterprises that have gotten ahead of the governance gap generally converge on the same five controls, applied before code reaches a production endpoint:

Define which tools are approved, and for what. Not every vibe coding tool should be allowed to touch every kind of workload. Internal dashboards and low-risk operational tools are a reasonable starting point; anything touching regulated data (PHI, PCI, PII) needs a platform with compliance controls attached by default, not bolted on later.
Require human review before infrastructure or schema changes ship. An agent proposing a database migration or an IAM policy change is fine. An agent applying it unilaterally is how you end up as a statistic in the next vulnerability scan. Review gates are the single highest-leverage control in this list.
Put secrets in a vault, never in generated code. Hardcoded credentials are one of the most consistently identified issues in scans of AI-generated code. An encrypted secrets vault with runtime injection removes the failure mode entirely rather than relying on the agent to remember not to do it.
Log every automated action. If an agent deployed it, scaled it, or rolled it back, that action needs to be attributable and reviewable after the fact. Security and compliance teams cannot govern what they cannot see.
Deploy inside a perimeter you control. For regulated workloads especially, "which cloud account is this actually running in" needs a straightforward answer. Vendor-hosted, shared infrastructure makes that answer harder than it needs to be.

Organizations that put structured frameworks like this in place report meaningfully faster remediation when something does go wrong, without giving up the development speed that made vibe coding worth adopting in the first place.

How NEXUS AI implements each control

NEXUS AI extends the same natural-language workflow teams already use to generate an app through deployment, with these five controls attached by default:

Approved-tool boundary: the AI App Builder generates and verifies code in an isolated development sandbox before anything is deployed.
Review gates: the database intelligence layer lets an agent propose schema fixes from runtime logs, but every change is reviewed by a human before it is applied.
Secrets vault: every deployment gets an AES-256-GCM encrypted secrets vault, with values injected at runtime and never written into the container image.
Audit log: every automated action, by a user or an MCP-connected agent, is recorded and reviewable.
Your own cloud, or ours: NEXUS AI Enterprise deploys on-premises, inside your own AWS, Google Cloud, or Azure account, or in a hybrid mix of both. Shared, multi-tenant infrastructure is available but never mandatory.

See the full breakdown on the vibe coding for the enterprise page, or the compliance controls on the security and HIPAA and compliance pages if the workload touches regulated data.

Common mistakes enterprises make with vibe coding

Treating governance as a launch blocker instead of a default. Bolting review, secrets management, and audit logging onto an existing vibe-coded app after the fact is far more expensive than starting with a platform that ships them by default.
Banning the workflow instead of governing it. Prohibition policies get worked around. Teams that need to move fast will use an ungoverned tool on a personal account rather than wait for IT to approve a governed one. The fix is to make the governed path the fast path.
Assuming code review catches what secret scanning would. Human reviewers are good at logic and architecture; they are inconsistent at spotting a hardcoded API key in a 400-line diff. Automated secrets detection and a vault are not optional.
Skipping the audit log because "nothing has gone wrong yet." The value of an audit trail is realized entirely after something goes wrong. By then, it is too late to start logging.

FAQ

What percentage of AI-generated code has security vulnerabilities?
A 2026 scan of over 1,400 vibe-coded production applications by Escape.tech, reported via a Cloud Security Alliance research note, found that 65% had a security issue and 58% shipped with at least one critical vulnerability, including exposed secrets and personally identifiable information.

How much enterprise software will actually be vibe coded?
Gartner's May 2025 report "Why Vibe Coding Needs to Be Taken Seriously" forecasts that 40% of new enterprise production software will be built using vibe coding techniques by 2028.

Is vibe coding safe to use for production applications?
Not by default. Published scans of vibe-coded apps show high rates of security issues and critical vulnerabilities when code goes straight from prompt to production with no review layer. Enterprise vibe coding platforms close that gap with mandatory human review, an encrypted secrets vault, RBAC, and a full audit log before anything ships.

What does "vibe coding for the enterprise" mean, specifically?
It means giving teams that already use AI to generate application code a sanctioned, governed path to production, instead of prototypes running on laptops or personal cloud accounts outside IT review.

Does adding governance controls slow down vibe coding?
Not meaningfully, if the controls are built into the platform rather than added as a separate process. A review gate on infrastructure changes and an automatic secrets vault add seconds, not days, when they are part of the deploy workflow instead of a follow-up ticket.

The gap between vibe coding adoption and vibe coding governance is not going to close on its own. It closes when the platform generating the code is the same platform enforcing review, secrets management, access control, audit logging, and deployment into a cloud account the enterprise actually controls.

See vibe coding for the enterprise applied. Or talk to sales about a governed path to production for your team.

NEXUS AI RBAC Deep Dive

Saif Ali — Sat, 15 Aug 2026 14:45:44 +0000

RBAC deep dive: roles, scopes, and least privilege

Published: August 15, 2026

Category: Security · Platform

Reading time: 14 minutes

Author: NEXUS AI Team

A developer leaves the company on Friday. By Monday, their credentials still open three production deployments, two billing pages, and a secrets vault they haven't touched in four months.

That's not a people problem. That's an access model problem.

Role-Based Access Control (RBAC) is how NEXUS AI answers the question every engineering org eventually asks: who can do what, to which resources, and how do we prove it? This post goes deep the role hierarchy, how scopes layer on top of roles, how least privilege works in practice, and how to design an access model your team will actually maintain.

Why RBAC matters more as your team scales

When it's just you, every door being open is convenient. When you have a team of 12 across three environments, every door being open is a liability.

The breach surface for a SaaS product running on cloud infrastructure is rarely the infrastructure itself. It's the humans and automated systems that have standing access to it:

A contractor with admin access granted for a two week engagement and never revoked.
A CI/CD token with full secrets:write permission because it was "easier to set up that way."
A junior developer who can redeploy production because the staging role got copy-pasted.

NEXUS AI's RBAC system is designed to make the right permission easy to grant and hard to accidentally expand. Least privilege is the default, not a setting you have to configure.

The role hierarchy

NEXUS AI defines four built-in roles. They are ordered by permission level each role is a strict superset of the one below it.

Role	Who it's for	What it controls
Viewer	Stakeholders, auditors, QA observers	Read-only access to deployments, logs, and metadata
Developer	Engineers doing day-to-day deployment work	Deploy, redeploy, rollback; read secret names (not values)
Admin	Team leads, platform engineers	Full control of deployments, secrets, tokens, and members
Owner	Founder, CTO, or designated security lead	Everything Admin can do + delete the organization

One organization has exactly one Owner. Ownership can be transferred, but not duplicated. This prevents the "everyone is an Owner" pattern that makes incident response a guessing game.

Viewer

Viewers can observe nothing more.

✓ View deployment status (running, stopped, failed)
✓ Read build and runtime logs
✓ See deployment metadata (region, container count, uptime)
✓ View audit log summaries
✗ Trigger any action (deploy, redeploy, rollback, stop)
✗ See secret names or values
✗ Create or revoke Access Tokens
✗ Invite or remove team members

Use Viewer for: product managers monitoring deploy status, customer success checking uptime, external auditors reviewing activity logs, read-only access for contractors.

Developer

Developers can act on deployments. They cannot change platform configuration.

✓ Everything Viewer can do
✓ Deploy, redeploy, rollback, stop deployments
✓ View secret names (DATABASE_URL, STRIPE_KEY) never values
✓ Create Access Tokens scoped to deploy:read and deploy:write only
✗ Create, update, or delete secrets
✗ Create tokens with admin or secrets:write scope
✗ Invite or remove organization members
✗ View billing or usage data

A Developer can push code and redeploy. They cannot change the secrets their code reads. The separation is intentional: it means a Developer-level compromise cannot extract production credentials, only trigger a redeploy.

Admin

Admins own the platform configuration for an organization.

✓ Everything Developer can do
✓ Create, update, and delete secrets
✓ Create Access Tokens with any scope
✓ Invite members and assign roles (up to Admin)
✓ View and export audit logs
✓ Manage domains, billing, and usage
✗ Delete the organization
✗ Transfer ownership
✗ Grant Owner role to another member

Limit Admin to people who actually need to configure secrets or onboard team members. In a 10-person startup, that's usually two or three people. In a 100-person company, it's a dedicated platform team.

Owner

The Owner role is structurally different from Admin it's not just "more permissions," it's accountability. Only one member holds it, and it carries the ability to perform irreversible actions.

✓ Everything Admin can do
✓ Delete the organization and all its resources
✓ Transfer ownership to another Admin
✓ Access all historical audit logs (including deleted members)

The Owner should be the person who is accountable for the business not necessarily the most technical. At a startup, that's the founding engineer or CTO. At an enterprise, it's the platform owner or CISO-designated lead.

How scopes work

Roles define what a human can do. Scopes define what a token can do.

When a Developer (or Admin) creates an Access Token, they can grant that token any scope up to but not exceeding their own permissions. A Developer cannot create a token with secrets:write scope, because Developers cannot write secrets directly.

This is scope containment: tokens cannot be a privilege escalation vector.

The full scope table

Scope	Read/Write	What it permits
`deploy:read`	Read	View status, logs, metadata for deployments
`deploy:write`	Write	Create, redeploy, rollback, scale, stop deployments
`secrets:read`	Read	List secret names for a deployment (never values)
`secrets:write`	Write	Create, update, delete secrets
`tokens:read`	Read	List tokens and their metadata
`tokens:write`	Write	Create and revoke Access Tokens
`members:read`	Read	List organization members and their roles
`members:write`	Write	Invite, remove, and change roles of members
`billing:read`	Read	View usage statistics and invoices
`billing:write`	Write	Update billing plan and payment method
`logs:read`	Read	Read build logs, runtime logs, and audit logs
`admin`	All	Full access equivalent to Admin role

Scopes compose. A CI token for a deployment pipeline typically needs deploy:write and nothing else. A token for a read-only monitoring integration needs deploy:read and logs:read. An MCP integration for an AI agent doing deployment management might need deploy:read,deploy:write,logs:read.

Creating a precisely scoped token

# CI/CD: deploy-only, expires in 90 days
nexus token create \
  --name "github-actions-prod" \
  --scopes deploy:write \
  --expires 90d

# Monitoring integration: read-only, no expiry (rotate quarterly via calendar)
nexus token create \
  --name "datadog-integration" \
  --scopes deploy:read,logs:read

# AI agent with deployment management access
nexus token create \
  --name "claude-mcp-agent" \
  --scopes deploy:read,deploy:write,logs:read \
  --expires 30d

# Admin token for a one time onboarding script (delete immediately after use)
nexus token create \
  --name "onboarding-script-2026-04-21" \
  --scopes admin \
  --expires 1d

The last example a short-lived admin token for a specific script, destroyed after use is exactly how temporary elevated access should work. No standing privileged access. No "just in case" tokens that accumulate over months.

Least privilege in practice

Least privilege is not a policy you write. It's a discipline you build into your provisioning process. Here's what it looks like in a real NEXUS AI team across three common scenarios.

Scenario 1: Onboarding a new backend engineer

Wrong approach:

New hire → Admin role → "they'll need it eventually"

Right approach:

New hire → Developer role
Week 1: pair with an Admin for any secrets work
Month 3: reassess do they actually need Admin? (usually no)

The Developer role covers 95% of what an active engineer does: deploy, redeploy, check logs, rollback a bad release. Secret creation is rare and can go through an Admin without slowing anyone down.

Scenario 2: Setting up a GitHub Actions pipeline

Wrong approach:

nexus token create --name "github-actions" --scopes admin
# Stored in GitHub secrets as NEXUS_API_KEY

Right approach:

# One token per environment, deploy:write only
nexus token create --name "github-actions-staging" --scopes deploy:write --expires 90d
nexus token create --name "github-actions-prod" --scopes deploy:write --expires 90d

# Store each in the corresponding GitHub environment secret
# github.com/org/repo → Settings → Environments → staging → NEXUS_API_KEY
# github.com/org/repo → Settings → Environments → production → NEXUS_API_KEY

Environment scoped tokens mean a staging pipeline compromise cannot touch production. The deploy:write scope means the pipeline can redeploy but cannot read or modify secrets.

Scenario 3: Granting an external contractor temporary access

Wrong approach:

Contractor → Admin role → "we'll remove it when they're done"
(They're done. It's still there. Six months later: breach.)

Right approach:

# Invite as Viewer they can observe, not act
nexus member invite contractor@agency.com --role Viewer

# If they need to trigger deploys, create a scoped token with explicit expiry
nexus token create \
  --name "contractor-agency-q2-2026" \
  --scopes deploy:write \
  --expires 30d

# Deliver the token via a secure channel. Calendar reminder for 29 days out.
# At project end: revoke the token and remove the member
nexus token revoke tok_01HX9...
nexus member remove contractor@agency.com

The token expires automatically even if you forget. The member removal is still important it cleans up the audit trail and signals a clean handoff.

Resource-level access: deployments and projects

Roles apply at the organization level by default. But NEXUS AI also supports project-scoped membership isolating access to a subset of deployments within an organization.

# Add a Developer to a specific project only
nexus project member add \
  --project payments-service \
  --email engineer@company.com \
  --role Developer

# They can now deploy payments-service/* deployments
# They cannot see auth-service/*, user-service/*, or any other project

Project-scoped access is useful for:

Regulated workloads — your payments team accesses the payments project; your analytics team accesses the analytics project. No overlap.
Multi-tenant organizations agencies managing deployments for multiple clients. Each client's project is isolated.
Contractor access — limit a vendor to exactly the project they're working on.

Organization-level Admins retain visibility across all projects. Project-scoped Developers cannot see outside their project boundary.

RBAC and AI agents

NEXUS AI's 37 MCP tools for Claude and AI agents operate under the same RBAC model as human callers. A token issued to an AI agent carries exactly the same scope enforcement no exceptions.

This matters because AI agents tend to be given more access than they need "because it's easier." An agent with admin scope that goes wrong is a full organization compromise. An agent with deploy:read that goes wrong reveals status information and nothing else.

Designing safe agent access

Read-only diagnostic agent — Claude inspects logs, checks deployment health, surfaces anomalies:

nexus token create \
  --name "claude-diagnostic" \
  --scopes deploy:read,logs:read \
  --expires 7d

The agent cannot deploy, rollback, or change anything. It observes and reports.

Deployment automation agent — Claude reacts to CI signals and triggers redeployments:

nexus token create \
  --name "claude-deploy-agent" \
  --scopes deploy:read,deploy:write,logs:read \
  --expires 30d

The agent can act on deployments. It cannot touch secrets, billing, or team membership.

Incident response agent — Claude triages a production incident, can rollback if needed:

# Short-lived, manually issued during an incident
nexus token create \
  --name "claude-incident-2026-04-21" \
  --scopes deploy:read,deploy:write,logs:read \
  --expires 4h

4-hour expiry. The token disappears when the incident window ends. No standing elevated access for AI agents.

The rule: grant an AI agent the minimum scope it needs to complete its defined task. Then set an expiry that matches the task duration — not "never" because that's convenient.

What RBAC cannot do

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

RBAC does not protect against a compromised Owner account. The Owner role has full access. If an Owner's credentials are compromised, the attacker has full access. Protect Owner accounts with hardware MFA, not just TOTP.

RBAC does not prevent a Developer from logging sensitive data. If your application logs process.env.DATABASE_URL at startup, that value appears in runtime logs — which Developers can read. Secret management starts with application code discipline.

RBAC does not enforce network-level isolation. A Developer with deploy:write can push a container that opens a reverse shell. Pair RBAC with container security policies and network egress controls for workloads that require it.

RBAC does not replace secrets rotation. Least privilege reduces blast radius when a secret is compromised. Rotation reduces the window of exposure. Both are required for a complete security posture.

The access model audit

Run this quarterly. It takes 20 minutes and it will find something to fix every time.

# List all organization members and their roles
nexus member list

# List all active tokens with creation date and last-used date
nexus token list --show-last-used

# Check for tokens with no expiry
nexus token list --no-expiry

# Check for tokens unused in 30+ days
nexus token list --unused-since 30d

For each token unused in 30+ days: revoke it. For each admin-scoped token that isn't for a one-time script: replace it with narrower scopes. For each member at a role higher than their current responsibilities: downgrade it.

The goal is to reach a state where every active token has a name that explains exactly what it does, an expiry that matches how long it needs to exist, and the minimum scope to do its job.

RBAC and compliance

If you're in a regulated industry healthcare, fintech, legal — RBAC is table stakes for compliance. NEXUS AI's RBAC system maps directly to common control requirements:

Compliance requirement	NEXUS AI control
Least-privilege access	Role hierarchy + token scopes
Separation of duties	Developers cannot write secrets; Owners are unique
Access review	`nexus member list`, `nexus token list` for quarterly audits
Privileged access management	Admin and Owner roles with MFA enforcement
Access revocation on termination	`nexus member remove` + `nexus token revoke`
Audit trail	Append-only audit logs with actor, token ID, timestamp, and IP

Enterprise and Enterprise On-Prem plans include 90-day and indefinite audit log retention respectively. Logs are exportable to Datadog, Grafana, Splunk, or any SIEM via the audit log export API.

Checklist: production-grade RBAC setup

[ ] Assign roles at the minimum level needed start with Developer, escalate to Admin only when demonstrated necessary
[ ] No team member should have Owner role unless they're accountable for the organization
[ ] Every CI/CD pipeline uses a separate deploy:write token per environment
[ ] Every token has a name that identifies its purpose and a --expires flag
[ ] No admin-scoped tokens in standing use only for one-time scripts with 1-day expiry
[ ] AI agent tokens scoped to exactly what the agent does (not admin)
[ ] Quarterly access review: nexus token list --unused-since 30d and nexus member list
[ ] Project-scoped membership for workloads that should be isolated (payments, healthcare, multi-client)
[ ] Owner account protected with hardware MFA (YubiKey or equivalent)
[ ] Offboarding runbook: member remove + all associated tokens revoke, same day

Frequently asked questions

Can a Developer see their own Access Tokens after creation?

Token values are shown once at creation — never again. A Developer can list their tokens by name and ID (nexus token list --mine), but the token_value is never retrievable. If lost, rotate.

What happens to tokens when a member is removed?

Tokens are scoped to the organization, not to the member who created them. Removing a member does not automatically revoke their tokens. Run nexus token list --created-by email@company.com and revoke manually as part of offboarding. A future release will offer member-removal with automatic token revocation.

Can a Developer escalate their own role?

No. Role changes require Admin or Owner. A Developer cannot call any API endpoint that modifies their own or another member's role.

How does NEXUS AI handle role changes mid-session?

Role and scope changes take effect immediately. An active API session using a token that gets revoked will receive a 401 Unauthorized on the next call — there's no grace window for human sessions (only for the 5-minute deploy token rotation window).

Is there a way to grant time-limited elevated access without creating a token?

Not currently at the role level — role changes are persistent until manually reverted. Use a short-lived admin-scoped token for temporary elevated operations instead of upgrading a member's role. This keeps the audit trail cleaner and eliminates the "I forgot to downgrade them" failure mode.

We're on the Starter plan. Do we get RBAC?

Yes. All four roles and the full scope system ship on every plan, including Starter at $29/mo. Project-scoped membership and audit log export are Enterprise features.

What's next

Access control works best when it's boring when every token has a clear purpose, every role is appropriate, and your quarterly audit finds nothing to clean up. That state is achievable. It requires an initial setup investment of about two hours and 20 minutes of discipline every quarter.

Start with your CI/CD tokens. Replace any admin-scoped pipeline token with deploy:write. That one change eliminates your largest standing access risk.

For regulated workloads, compliance tooling, or teams larger than 20 engineers, the Enterprise plan adds SAML SSO, custom audit log retention, and dedicated security review. Reach out at nexusai.run.

Related reading:

Stop shipping secrets. Start using a vault.
MCP integration: 37 tools for Claude and AI agents
Audit logs and compliance: what gets recorded and why
How NEXUS AI deploys your app in under 5 minutes

Least privilege is not paranoia. It's the discipline that makes incidents containable.

NEXUS AI One-Prompt Deployment Is Here Just Describe It and Ship It

Saif Ali — Sat, 15 Aug 2026 14:37:32 +0000

One Prompt Deployment Is Here Just Describe It and Ship It

Tell it what you want. Watch it deploy.

Headline Options

One-Prompt Deployment Is Here Just Describe It and Ship It
Deploy With Words: Introducing One-Prompt Deployment
Forget the Config — Just Tell It What to Deploy

There's a version of deployment that feels like magic. You describe what you want — in plain English, in a single line — and your app is live. No YAML. No CLI flags. No digging through docs to remember what --replicas does in this context.

That version of deployment exists now. Meet One-Prompt Deployment.

What Is One-Prompt Deployment?

One-Prompt Deployment lets you trigger and configure deployments using natural language. Instead of writing pipeline configs or remembering command syntax, you just describe your intent:

"Deploy the latest build of the payments service to staging with 3 replicas and a 5-minute timeout."

That's it. The system interprets your intent, maps it to the right configuration, runs pre-flight checks, and ships it all without you touching a config file or terminal command.

It's not a chatbot wrapped around a deploy button. Under the hood, it's a structured inference layer that translates natural language into validated deployment operations, with full auditability and rollback built in.

Why We Built This

Deployment tooling has gotten incredibly powerful over the last decade but with that power came complexity. Kubernetes configs, Helm charts, custom CI/CD pipelines: each layer adds capability, but also adds surface area to learn, maintain, and debug.

We wanted to give developers the full power of that tooling without requiring them to become experts in every layer of it. One-Prompt Deployment is the result: a natural language interface that sits on top of your existing infrastructure and makes it approachable for everyone on the team.

What Makes It Different

It Moves at the Speed of Thought

The fastest interface is the one where you don't have to translate your intent into syntax. With One-Prompt Deployment, you describe what you want in natural language and the system handles the translation. In practice, this means going from "I want to deploy this" to "it's deployed" in under two minutes including the time it takes to type the prompt.

No more context-switching to look up CLI flags or YAML schema. No more copy-pasting config from a deployment that worked last time. Just describe it and ship it.

Works With Your Stack, Out of the Box

One-Prompt Deployment understands the vocabulary of your existing infrastructure. Connect it to your cloud provider, container registry, and environment configs, and it immediately knows the names of your services, your environment tiers, and your deployment conventions.

That means your prompts can be natural and specific: "Roll out the new auth service to production using the blue/green strategy" — and it knows exactly what "auth service," "production," and "blue/green" mean in your context. No training required, no custom setup beyond your existing connections.

Guardrails Built In — Not Bolted On

Natural language is flexible, which means there's room for ambiguity. We take that seriously. Before any deployment runs, the system surfaces a confirmation summary showing exactly what it understood and what it's about to do. You review, approve, and then it executes.

If something looks off at the pre-flight stage, it halts and explains why — with a suggested fix in plain language. And if a deployment does go wrong post-launch, automatic rollback restores your last stable state, no incident bridge required.

Unlocks Deployment for Your Whole Team

This is the one we're most excited about. Traditionally, production deployments are gatekept not because teams want them to be, but because the tooling is too complex for anyone outside of platform or DevOps to use safely.

One-Prompt Deployment changes that calculus. QA engineers can deploy to staging environments without waiting on a pipeline engineer. Product managers can trigger approved releases without opening a terminal. On-call rotations can use it to execute rollbacks without institutional knowledge of your infra.

Your deployment process doesn't have to be a bottleneck anymore.

Getting Started

Enabling One-Prompt Deployment takes about five minutes:

Navigate to Settings → Deployments → Prompt Mode in your dashboard
Connect your infrastructure integrations (cloud provider, registry, environments)
Run a test prompt to confirm your context is loaded correctly
Start deploying

Full documentation including prompt syntax tips, advanced configuration, and the API reference for programmatic prompt-triggered deployments is in our developer docs.

What's Coming Next

We're already building on this foundation. Next up: prompt-based deployment schedules ("deploy every Friday at 5pm if all tests pass"), multi-service orchestration prompts, and a prompt history log with diff views so you can audit exactly what was deployed and when.

We'd love your feedback as you use it. Join the conversation in our community Discord, open a GitHub Discussion, or just reply to this post. The best features we've built have come directly from developers telling us what's broken or missing — and this one is no different.

Ship the thing. We've handled the rest. 🚀

Author: [NEXUS AI Team]
Published: [8/15/2026]
Tags: deployments, developer tools, AI, natural language, CI/CD, new feature, engineering

Getting Started: NEXUS AI Connector on Claude

Saif Ali — Sat, 15 Aug 2026 14:30:38 +0000

Getting Started: NEXUS AI Connector on Claude

Your entire deployment platform, accessible through a single conversation.

Headline Options

Getting Started: NEXUS AI Connector on Claude
Control NEXUS AI With Claude — No Dashboard Required
Meet the NEXUS AI Connector: Deploy, Monitor, and Manage With Just a Prompt

What if you could deploy an app, check its health, spin up a database, and rotate a secret — all without leaving your AI assistant? No tab-switching, no dashboard hunting, no copy-pasting deployment IDs.

That's exactly what the NEXUS AI Connector for Claude makes possible. It connects your NEXUS AI account directly to Claude, giving you full control of your infrastructure through natural language. This guide walks you through getting set up and making your first prompt-driven deployment in under ten minutes.

What Is the NEXUS AI Connector?

The NEXUS AI Connector is an MCP (Model Context Protocol) integration that exposes your NEXUS AI platform — deployments, databases, secrets, domains, and more — as tools Claude can use on your behalf.

Once connected, Claude isn't just answering questions about your infrastructure. It's actually interacting with it: listing your running deployments, reading logs, scaling services, and executing the same operations you'd normally do through the dashboard or CLI.

Think of it as a natural language interface sitting on top of everything NEXUS AI can do.

What You Can Do With It

Here's a quick taste of what you can ask Claude once the connector is set up:

"List all my running deployments"
"Deploy the latest build of my API service to staging"
"Show me the last 50 runtime logs for the payments service"
"Create a new secret called DATABASE_URL for the production environment"
"Add a custom domain to my frontend deployment"
"Scale my backend service to 3 replicas"
"What's the health status of my production deployments?"

No syntax to memorize. No CLI to install. Just describe what you need.

Getting Started in 3 Steps

Step 1: Connect Your NEXUS AI Account

Open Claude and navigate to Settings → Connectors. Find the NEXUS AI Connector in the list and click Connect. You'll be prompted to authenticate with your NEXUS AI credentials — this uses a secure OAuth flow, so your credentials are never stored in the conversation.

Once authenticated, Claude will confirm that your account is linked and show you a summary of the resources it can access.

Tip: If you're on a Team or Enterprise plan, check with your org admin to make sure the NEXUS AI Connector is enabled in your workspace settings.

Step 2: Verify the Connection

Ask Claude something simple to confirm everything is working:

"What deployments do I have running right now?"

Claude will call the NEXUS AI API and return a list of your active deployments — names, statuses, providers, and environments. If you see your infrastructure listed back at you, you're good to go.

If Claude says it can't find any deployments, double-check that you connected the right NEXUS AI account and that your deployments are in a running or deploying state.

Step 3: Try Your First Prompt-Driven Action

Now for the fun part. Try a real operation:

"Deploy nginx:latest to port 80 in my development environment."

Claude will use the NEXUS AI Connector to kick off the deployment, then confirm what it's doing before executing. Once it's underway, you can follow up:

"What's the status of that deployment?"
"Show me the build logs."
"Is it healthy yet?"

Claude handles the back-and-forth with the API so you can stay in the conversation flow instead of jumping to the dashboard.

A Few Things Worth Knowing

Actions that modify your infrastructure require confirmation. Before Claude executes anything that changes state — deploys, scales, deletes, or modifies secrets — it will summarize what it's about to do and ask you to confirm. This is intentional. You stay in control.

Sensitive values are protected. When you ask Claude to create or update secrets, it will execute the operation but will never display secret values in the conversation. What goes into NEXUS AI stays in NEXUS AI.

Your logs and metrics are available inline. Ask Claude to pull logs mid-conversation and it will surface them directly — no need to open a separate terminal or dashboard tab. You can filter by log type, limit line counts, or ask Claude to highlight errors for you.

Everything is auditable. Every operation Claude performs via the connector maps to a real NEXUS AI API call. Your audit trail in NEXUS AI reflects all activity, whether it was initiated through the dashboard, CLI, or Claude.

What's Possible When You Put It Together

Once you're comfortable with the basics, the connector really shines in more complex workflows:

Debug faster: Ask Claude to pull logs, identify errors, propose a fix, and redeploy — all in a single conversation thread
Incident response: In a live incident, describe the symptoms and ask Claude to check deployment health, pull recent logs, and execute a rollback if needed
Onboarding: New engineers can interact with production-adjacent environments without needing to learn every CLI tool in your stack
Routine ops: Automate repetitive deployment checks or environment refreshes by describing what you need rather than scripting it

Ready to Try It?

The NEXUS AI Connector is available now. Head to your Claude settings, connect your account, and start your first session. The full list of supported operations — deployments, databases, secrets, domains, logs, health checks, and more — is documented in our connector reference docs.

If you run into anything unexpected, drop a message in our community Discord or open a support ticket directly from your NEXUS AI dashboard.

Your infrastructure is one prompt away. 🚀

Author: [Saif Ali]
Published: [4/20/2026]
Tags: NEXUS AI, Claude, MCP, connector, deployments, developer tools, getting started, AI infrastructure

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.