Forem: Saif Ali

NEXUS AI RBAC

Saif Ali — Sat, 25 Apr 2026 22:38:05 +0000

RBAC deep dive: roles, scopes, and least privilege

Published: April 21, 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.

Stop shipping secrets. Start using a vault

Saif Ali — Sat, 25 Apr 2026 21:47:39 +0000

Stop shipping secrets. Start using a vault.

Published: April 21, 2026

Category: Security · DevOps

Reading time: 12 minutes

Author: NEXUS AI Team

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

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

The problem with secrets in 2026

Most teams manage secrets in one of three ways:

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

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

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

The NEXUS AI Secrets Vault

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

How encryption works

When you store a secret, NEXUS AI:

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

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

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

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

What the vault does NOT do

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

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

Secure Configuration Injection

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

The sequence:

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

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

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

Access Tokens

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

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

Token anatomy

Every NEXUS AI Access Token carries three pieces of information:

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

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

Creating a token

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

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

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

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

Token scopes

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

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

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

Token expiry and rotation

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

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

Rotate before expiry:

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

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

Secrets + Tokens in a real pipeline

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

Step 1: Store secrets once

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

Step 2: Create a scoped CI token

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

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

name: Deploy to production

on:
  push:
    branches: [main]

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

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

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

Step 4: Runtime

When the container starts, it finds:

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

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

RBAC and the audit trail

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

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

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

The audit log

Every secret operation and token use is recorded:

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

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

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

MCP: AI agents and your secrets vault

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

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

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

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

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

Checklist: zero-plaintext secrets in 10 minutes

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

Frequently asked questions

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

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

What happens to secrets if I delete a deployment?

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

How do I handle secrets that multiple deployments share?

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

Can a Developer-role member read secret values?

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

What encryption key does NEXUS AI use?

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

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

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

What's next

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

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

Related reading:

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

Ship what matters. Lock down the rest.

NEXUS AI Audit

Saif Ali — Sat, 25 Apr 2026 21:45:13 +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.

Serverless deployment with NEXUS AI

Saif Ali — Sat, 25 Apr 2026 21:42:10 +0000

Serverless deployment with NEXUS AI: custom domains, scaling, rollback, and more

Published: April 25, 2026

Category: Platform · DevOps

Reading time: 16 minutes

Author: NEXUS AI Team

Serverless means different things to different teams. For most, it means: don't manage servers, don't think about capacity until it matters, and pay for what you actually run. That premise is right. The implementation — tangled cloud console configurations, provider-specific YAML, and per-cloud IAM policies — is where the promise breaks down.

NEXUS AI deploys containerized applications to AWS App Runner, Google Cloud Run, and Azure Container Apps from a single CLI command. No cloud console. No provider-specific configuration files. Custom domains, replica scaling, one-click rollback, and health checks work the same way across all three.

This post covers every production feature in detail: how it works, what it costs, and the exact CLI commands to run it.

How NEXUS AI serverless works

NEXUS AI acts as a deployment orchestration layer on top of the three major serverless container runtimes:

Provider	Runtime	What runs your container
`GCP_CLOUD_RUN`	Google Cloud Run	Google's fully managed serverless container platform
`AWS_APP_RUNNER`	AWS App Runner	AWS's fully managed container runtime
`AZURE_CONTAINER_APPS`	Azure Container Apps	Azure's serverless container service
`LOCAL_DOCKER`	NEXUS AI managed	NEXUS AI's own managed Docker infrastructure

You choose the provider at deploy time. NEXUS AI handles the cloud-side provisioning — service creation, IAM, registry, networking — and gives you a live URL within minutes. Switching providers is a single flag change on the next redeploy.

Your container runs on your cloud account (Pro and above), not on shared NEXUS AI infrastructure. The data and workload stay in your AWS, Google Cloud, or Azure environment.

Your first serverless deployment

Deploy from a Git repository in one command:

nexus deploy source \
  --name api-prod \
  --repo https://github.com/your-org/your-api \
  --branch main \
  --provider GCP_CLOUD_RUN \
  --region us-central1 \
  --port 3000

Or deploy a pre-built container image:

nexus deploy create \
  --name api-prod \
  --image ghcr.io/your-org/api:latest \
  --provider AWS_APP_RUNNER \
  --region us-east-1 \
  --port 3000

Within 3–5 minutes, your deployment is live at a *.nexusai.run subdomain:

✓ Deployment api-prod created
  URL:      https://api-prod.nexusai.run
  Provider: AWS_APP_RUNNER (us-east-1)
  Status:   RUNNING
  Replicas: 1

No Dockerfile required if you deploy from source — NEXUS AI detects your runtime and generates one. No registry setup, no IAM policy documents, no VPC configuration.

Environments

Every deployment belongs to an environment: DEVELOPMENT, STAGING, or PRODUCTION. Environments affect:

Which secrets are injected (secrets are scoped per environment)
Which team members can deploy (RBAC enforces environment-level permissions)
Which providers are available (controlled by your org's provider config)

# Deploy the same app to staging and production as separate deployments
nexus deploy source --name api-staging --env staging --provider GCP_CLOUD_RUN ...
nexus deploy source --name api-prod    --env production --provider AWS_APP_RUNNER ...

Staging and production run independently — different secrets, different provider configs, same codebase. A bad deploy to staging never touches production.

Custom domains

Every deployment gets a *.nexusai.run subdomain automatically. For production workloads, attach your own domain.

Add a custom domain

nexus domain add api-prod app.yourcompany.com

Output:

✓ Domain app.yourcompany.com added to api-prod
  Verification: PENDING

  Add this DNS record at your registrar:

  Type:  CNAME
  Name:  app
  Value: api-prod.nexusai.run

Verify DNS

Once you've added the CNAME record at your registrar, trigger verification:

nexus domain verify api-prod <domain-id>

NEXUS AI checks DNS propagation and issues a TLS certificate automatically. Verification typically completes within 2–10 minutes of DNS propagation, which depends on your TTL settings.

Apex domains

Both subdomain (app.yourcompany.com) and apex (yourcompany.com) are supported. For apex domains, use your registrar's ALIAS or ANAME record (or CNAME flattening if your registrar supports it) pointing to api-prod.nexusai.run.

List and remove domains

# List all domains for a deployment
nexus domain list api-prod

# Remove a domain
nexus domain remove api-prod <domain-id>

Custom domains are available on Starter ($29/mo) and above. The Free plan uses *.nexusai.run subdomains only.

Scaling

Scale a running deployment between 1 and 10 replicas with a single command. No redeploy required — scaling applies to the live deployment immediately.

# Scale up before a high-traffic event
nexus deploy scale api-prod --replicas 5

# Scale back down after
nexus deploy scale api-prod --replicas 2

Output:

✓ api-prod scaled to 5 replica(s)
  Previous: 2
  Current:  5
  Provider: GCP_CLOUD_RUN

On Google Cloud Run, AWS App Runner, and Azure Container Apps, scaling is applied directly to the underlying service — NEXUS AI calls the provider's API to set the replica count and the change takes effect within 30–60 seconds.

Replica limits

The maximum is 10 replicas per deployment across all plans. For workloads requiring more than 10 replicas, use the provider's native auto-scaling configuration directly on the cloud console alongside NEXUS AI's managed deployment.

Scaling and cost

Replicas run continuously on App Runner and Cloud Run until you scale back down. They are not auto-scaled to zero. If you need scale-to-zero, configure minimum instances on the underlying provider or use the nexus deploy stop command to halt a deployment entirely during off-hours.

# Stop during off-hours
nexus deploy stop api-staging

# Restart when needed
nexus deploy start api-staging

Health checks

NEXUS AI configures health checks on every deployment. A deployment that fails health checks is automatically flagged — and if it stays unhealthy past the retry threshold, it surfaces in both the dashboard and your audit log.

Configuration

Health checks are configured at deploy time:

nexus deploy source \
  --name api-prod \
  --health-check-type http \
  --health-check-url /health \
  --health-check-interval 30 \
  --health-check-timeout 3 \
  --health-check-retries 3 \
  --health-check-start-period 40 \
  ...

Parameter	Default	What it does
`--health-check-type`	`http`	`http`, `tcp`, or `none`
`--health-check-url`	`/health`	Endpoint checked for HTTP type
`--health-check-interval`	30s	Seconds between checks
`--health-check-timeout`	3s	Max wait per check
`--health-check-retries`	3	Failures before marking unhealthy
`--health-check-start-period`	40s	Grace period before checks begin

The 40-second start period is the most important default to understand. It gives your container time to initialize before health checks begin — a Node.js app loading large models or a Java app with a slow JVM startup won't be marked unhealthy before it's ready.

Check current health status

nexus deploy status api-prod

NAME       STATUS   HEALTH    REPLICAS  RESTARTS  PROVIDER         UPTIME
api-prod   RUNNING  healthy   2         0         AWS_APP_RUNNER   14h ago

Rollback

Redeploy to a previous known-good state with one command. No rebuilding, no config archaeology.

nexus deploy rollback api-prod

Rollback is available on Pro ($149/mo) and above. On Free and Starter plans, rollback is not available — the recovery path is a new deployment from the previous image tag or branch.

How rollback works

NEXUS AI stores the previous deployment configuration — image, environment variables, secrets references, provider, region, and replica count. When you rollback, it provisions a new deployment using that configuration. The original deployment record is preserved in your history.

# Check deployment history before rolling back
nexus deploy list --json | jq '.[] | select(.name | startswith("api-prod"))'

[
  { "name": "api-prod",          "status": "FAILED",  "createdAt": "2026-04-25T14:22:00Z" },
  { "name": "rollback-k3x9ab2",  "status": "RUNNING", "createdAt": "2026-04-25T14:30:00Z" }
]

The rollback deployment gets a generated name (rollback-{timestamp}) and runs at the same replica count as the original.

Secrets and environment variables

Secrets are injected at runtime — never baked into the container image. Set them once; they're available across redeployments.

# Store secrets in the vault
nexus secret set DATABASE_URL "postgres://..." --environment production
nexus secret set STRIPE_SECRET_KEY "sk_live_..." --environment production
nexus secret set OPENAI_API_KEY "sk-..." --environment production

# Deploy — secrets are automatically injected
nexus deploy source --name api-prod --env production ...

Your application reads them as standard environment variables:

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

No SDK. No fetch-on-startup. No cold-start penalty from secret retrieval. Secrets are decrypted in the NEXUS AI control plane and injected into the container spec before the first process starts.

Environment variables that aren't secrets can be passed inline at deploy time:

nexus deploy source \
  --name api-prod \
  --env-var NODE_ENV=production \
  --env-var LOG_LEVEL=info \
  --env-var PORT=3000 \
  ...

Multi-service deployments

NEXUS AI supports Docker Compose deployments for applications that require multiple services running together — an API, a background worker, and a Redis sidecar, for example.

nexus deploy source \
  --name platform-prod \
  --repo https://github.com/your-org/platform \
  --compose \
  ...

When --compose is specified, NEXUS AI reads your docker-compose.yml, provisions each service as a deployment, and wires them together within the same project. Services can reference each other by name on the internal network.

Redeploy

Push a new image or rebuild from source without changing any configuration:

# Redeploy from the same source (pulls latest from the branch)
nexus deploy redeploy api-prod

# Or from CI/CD using an Access Token
NEXUS_API_KEY=nxk_... nexus deploy redeploy api-prod

Redeployments on cloud providers (AWS App Runner, Google Cloud Run, Azure Container Apps) complete in 60–90 seconds. The old revision stays running until the new one passes health checks — zero-downtime by default.

CI/CD integration

A typical GitHub Actions pipeline with NEXUS AI:

name: Deploy to production

on:
  push:
    branches: [main]

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

      - name: Build and push image
        run: |
          docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
          docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

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

The pipeline token uses deploy:write scope only — it cannot read secrets, change configuration, or touch other deployments. One compromised pipeline token is one redeployment trigger, nothing more.

Auto-destroy

Temporary deployments — review apps, QA environments, demo instances — can be set to self-destruct after a fixed window:

# Spin up a review deployment that destroys itself after 24 hours
nexus deploy source \
  --name pr-1234-review \
  --auto-destroy 24h \
  ...

The deployment runs normally until the deadline, then stops and cleans up its cloud resources automatically. No manual teardown required, no forgotten review apps billing at end of month.

Real-time logs

Stream build and runtime logs for any deployment:

# Follow runtime logs
nexus deploy logs api-prod --follow

# Get last 200 lines
nexus deploy logs api-prod --tail 200

# Filter by keyword
nexus deploy logs api-prod --follow | grep ERROR

Logs are available within seconds of a container writing to stdout/stderr. Build logs (the image build, Dockerfile execution, dependency installation) are also accessible via the same command with --build.

Plan comparison

Feature	Free	Starter ($29/mo)	Pro ($149/mo)	Enterprise
Deployments	1	2	5	Unlimited
Providers	Managed Docker	Docker + Google Cloud	All 4 providers	All 4 providers
Custom domains	—	✓	✓	✓
Rollback	—	—	✓	✓
Secrets	3	20	100	Unlimited
Team members	0	3	10	Unlimited
AI generations/day	1	10	Unlimited	Unlimited
Your cloud account	—	✓	✓	✓
Replica scaling (1–10)	✓	✓	✓	✓
Health checks	✓	✓	✓	✓
Audit logs	✓	✓	✓	✓

Deployment command reference

# Deploy from source
nexus deploy source --name <name> --repo <url> --branch <branch> --provider <provider> --port <port>

# Deploy from image
nexus deploy create --name <name> --image <image> --provider <provider> --port <port>

# Redeploy (same config, new build)
nexus deploy redeploy <name>

# Scale replicas (1–10)
nexus deploy scale <name> --replicas <n>

# Rollback to previous version (Pro+)
nexus deploy rollback <name>

# Stop / start
nexus deploy stop <name>
nexus deploy start <name>

# View status
nexus deploy status <name>

# Stream logs
nexus deploy logs <name> --follow

# List deployments
nexus deploy list

# Delete deployment
nexus deploy delete <name>

# Custom domains
nexus domain add <deployment> <domain>
nexus domain verify <deployment> <domain-id>
nexus domain list <deployment>
nexus domain remove <deployment> <domain-id>

Checklist: production-ready serverless deployment

[ ] Set all secrets via nexus secret set before first deploy — zero plaintext env vars
[ ] Configure --health-check-url to match your app's actual health endpoint
[ ] Set --health-check-start-period to at least your app's cold-start time
[ ] Create a scoped deploy:write token for CI/CD — never use your personal token in pipelines
[ ] Add your custom domain and verify DNS before announcing the URL
[ ] Run nexus deploy status <name> --watch on the first production deploy to catch health check failures early
[ ] Set --auto-destroy on review and QA deployments — prevent billing surprises
[ ] Scale to at least 2 replicas for production — single-replica deployments have no redundancy

Frequently asked questions

Which cloud provider should I use?

For most workloads: Google Cloud Run (GCP_CLOUD_RUN) for its zero-to-running speed and global network, AWS App Runner (AWS_APP_RUNNER) if your team already runs on AWS and wants everything in one account, Azure Container Apps (AZURE_CONTAINER_APPS) for Microsoft-stack integrations. All three behave identically from the NEXUS AI CLI perspective.

Does NEXUS AI support scale-to-zero?

Not natively managed from the CLI — replicas run continuously at whatever count you set. The underlying providers (Cloud Run, Container Apps) support scale-to-zero natively; you can configure it on the cloud console alongside NEXUS AI's deployment. nexus deploy stop halts the deployment entirely, which achieves zero cost during idle periods for non-production environments.

Can I bring my own Dockerfile?

Yes. If your repository includes a Dockerfile, NEXUS AI uses it. If not, it generates one based on detected runtime (Node.js, Python, Go, Java, etc.). You can also pass a Dockerfile path explicitly with --dockerfile.

How does rollback work on Cloud Run and App Runner?

NEXUS AI stores your previous deployment configuration and provisions a new deployment from it — it does not use the provider's native revision rollback. This means rollback works identically across all four providers and preserves a clean audit trail of every state the deployment has been in.

What happens if a deployment fails health checks?

The deployment status changes to FAILED or UNHEALTHY. For cloud providers, the previous revision stays running (Cloud Run and Container Apps keep the last healthy revision active). You'll see a DEPLOYMENT_FAILED event in your audit log with the exit code and error message. Run nexus deploy logs <name> to see what went wrong, then redeploy or rollback.

Can I run multiple services (API + worker + DB) in one deployment?

Use --compose to deploy a Docker Compose file. Each service in the compose file becomes a tracked service under the same deployment, connected on an internal network. External database connections should use NEXUS AI secrets rather than running a database container — ephemeral containers are not a reliable database host.

What's next

Start with a single command. If your app is already containerized:

nexus deploy create \
  --name my-app \
  --image your-registry/your-app:latest \
  --provider GCP_CLOUD_RUN \
  --port 3000

You'll have a live URL in under 5 minutes. Add your custom domain, wire up secrets, and set up your CI/CD pipeline — the entire production setup takes under an hour.

NEXUS AI starts at $29/mo on the Starter plan. Custom domains, Google Cloud Run deployments, and up to 3 team members are included. Start at nexusai.run.

Related reading:

Stop shipping secrets. Start using a vault.
RBAC deep dive: roles, scopes, and least privilege
Audit logs and compliance: what gets recorded and why
MCP integration: 37 tools for Claude and AI agents

No cloud console. No YAML. One command from prompt to production.

Deploy Flixty in minutes with NEXUS AI

Saif Ali — Thu, 09 Apr 2026 23:08:28 +0000

5 min read · Beginner friendly · April 2026

Flixty is an open-source, self-hosted social media creator studio that lets you publish to X, LinkedIn, Facebook, Instagram, TikTok, and YouTube from a single interface. NEXUS AI deploys it directly from source — no Dockerfile required — with a single MCP tool call.

This guide walks you through deploying Flixty on NEXUS AI step by step — covering provider selection, environment variable setup, OAuth configuration for each platform, and ongoing management. By the end you'll have a live, self-hosted social posting studio running on your own cloud infrastructure.

What is Flixty?

Flixty (github.com/nexusrun/flixty) is a Node.js 18+ Express application that serves as a unified control panel for social media publishing. It runs on port 3000 and is started with node server.js — no build step, no container image to maintain.

Key capabilities:

Multi-platform posting — schedule and publish content to X, LinkedIn, Facebook, Instagram, TikTok, and YouTube from one dashboard
AI Assist — optional Claude integration (via ANTHROPIC_API_KEY) generates captions, hashtags, and post variations
Post scheduler — queue posts for optimal publish times across time zones
Live streaming support — manage stream metadata and thumbnails alongside regular posts
OAuth per platform — each social network authenticates independently; add only the platforms you need

Prerequisites

A NEXUS AI account with at least one project configured
The NEXUS AI MCP connector enabled in Claude — or API access to api.zollo.live/mcp
A supported cloud provider account (GCP, AWS, or Azure)
OAuth credentials for each social platform you want to enable (X, LinkedIn, Facebook/Instagram, TikTok, Google/YouTube)

Tip: You can deploy Flixty without any platform credentials first to get the public URL, then add OAuth credentials in a redeploy. This is the recommended flow since most OAuth apps require a known redirect URI before you can obtain credentials.

Deploying Flixty — step by step

Step 1 — Choose your cloud provider

Flixty is deployed as a source-based deployment — NEXUS AI clones the repo, installs dependencies, and runs node server.js on your chosen provider. GCP Cloud Run is recommended for production: it handles auto-scaling and provides a stable HTTPS URL you can use for OAuth redirect URIs.

Provider	Notes
GCP Cloud Run	Serverless, auto-scales to zero
AWS ECS Fargate	Full AWS ecosystem
Azure Container Apps	Enterprise & compliance

Environments map to: PRODUCTION for live traffic (default), STAGING for pre-production validation, and DEVELOPMENT for local testing.

Step 2 — Deploy with one MCP tool call

Via the NEXUS AI MCP in Claude, call nexusai_deploy_flixty. A minimal invocation — with no platform credentials yet — looks like this:

nexusai_deploy_flixty(
  provider:    "gcp_cloud_run",
  environment: "PRODUCTION",
  name:        "flixty"  // optional
)

If you don't supply a sessionSecret, NEXUS AI auto-generates a cryptographically secure 64-character hex secret for your Express sessions. You can also pass platform OAuth credentials and an anthropicApiKey at this stage if you have them ready.

Or deploy from the CLI:

nexus deploy flixty \
  --provider gcp_cloud_run \
  --wait

Step 3 — Save your deployment credentials

After a successful deploy call, NEXUS AI returns:

Field	Description	Example
`id`	Deployment UUID	`7a2c91f0-…`
`sessionSecret`	Express session signing key	`4d8f1c3a9e…`
`status`	Current state	`queued` → `running`
`url`	Public HTTPS endpoint	Available once live

Important: Copy your sessionSecret immediately — it's returned once. Losing it means active user sessions will be invalidated on the next redeploy. Store it in NEXUS AI Secrets or your secrets manager.

Step 4 — Get the public URL and set BASE_URL

Once the deployment is running, retrieve its public URL and redeploy with BASE_URL set. This is required for OAuth redirect URIs to work correctly across all platforms.

nexusai_deploy_status(
  deploymentId: "7a2c91f0-…"
)

// Once you have the URL, redeploy with baseUrl:
nexusai_deploy_flixty(
  provider:      "gcp_cloud_run",
  baseUrl:       "https://flixty-abc123.run.app",
  sessionSecret: "your-saved-session-secret"
)

Use https://flixty.yourdomain.com/auth/<platform>/callback as the redirect URI when registering your OAuth apps on each platform.

Step 5 — Add platform OAuth credentials

Redeploy with credentials for each platform you want to enable. You can add them all at once or one at a time:

nexusai_deploy_flixty(
  provider:            "gcp_cloud_run",
  baseUrl:             "https://flixty.yourdomain.com",
  sessionSecret:       "your-saved-session-secret",
  xClientId:           "x-oauth-client-id",
  xClientSecret:       "x-oauth-client-secret",
  linkedinClientId:    "linkedin-client-id",
  linkedinClientSecret:"linkedin-client-secret",
  fbAppId:             "facebook-app-id",
  fbAppSecret:         "facebook-app-secret",
  googleClientId:      "google-client-id",
  googleClientSecret:  "google-client-secret",
  anthropicApiKey:     "sk-ant-…"  // enables AI Assist
)

Note: fbAppId and fbAppSecret enable both Facebook and Instagram. A single Facebook App handles both platforms via the Graph API.

Environment variables reference

All variables are injected securely at runtime. None are baked into the image.

Variable	Required	Description
`SESSION_SECRET`	Yes	Express session signing key. Auto-generated (64-char hex) if not provided.
`BASE_URL`	Yes*	Public HTTPS URL of your deployment. Required for OAuth redirect URIs. Set after first deploy.
`PORT`	Auto-set	Always `3000`. Set automatically by NEXUS AI.
`NODE_ENV`	Auto-set	Always `production` for PRODUCTION environment deployments.
`ANTHROPIC_API_KEY`	No	Enables AI Assist (claude-sonnet-4-6) for caption generation and post variations.
`X_CLIENT_ID`	No	X/Twitter OAuth 2.0 Client ID. Required to enable X posting.
`X_CLIENT_SECRET`	No	X/Twitter OAuth 2.0 Client Secret.
`LINKEDIN_CLIENT_ID`	No	LinkedIn OAuth Client ID. Required to enable LinkedIn posting.
`LINKEDIN_CLIENT_SECRET`	No	LinkedIn OAuth Client Secret.
`FB_APP_ID`	No	Facebook App ID. Enables both Facebook and Instagram via the Graph API.
`FB_APP_SECRET`	No	Facebook App Secret.
`TIKTOK_CLIENT_KEY`	No	TikTok Client Key. Required to enable TikTok posting.
`TIKTOK_CLIENT_SECRET`	No	TikTok Client Secret.
`GOOGLE_CLIENT_ID`	No	Google OAuth Client ID. Enables YouTube posting and Google Sign-In.
`GOOGLE_CLIENT_SECRET`	No	Google OAuth Client Secret.

*BASE_URL is technically optional on first deploy when the public URL is not yet known. Set it on the first redeploy once the deployment is running.

Managing your Flixty deployment

NEXUS AI gives you full lifecycle control over every deployment. Here's a quick reference:

Action	MCP Tool	When to use
Check status	`nexusai_deploy_status`	After deploying, or to get the public URL
View logs	`nexusai_deploy_logs`	Debug OAuth errors or startup failures
Redeploy	`nexusai_deploy_redeploy`	Push updated env vars or a new code revision
Stop studio	`nexusai_deploy_stop`	Pause to save compute costs
Restart	`nexusai_deploy_start`	After a stop, or after config changes
Rollback	`nexusai_deploy_rollback`	Revert to a previous working revision
Delete	`nexusai_deploy_delete`	Permanently tear down the deployment

Scaling your deployment

Scale Flixty up to handle more concurrent users without redeploying:

nexusai_deploy_scale(
  deploymentId: "7a2c91f0-…",
  replicas:     3
)

Or via the CLI:

nexus deploy scale flixty 3

Custom domain

Attach a custom domain so your OAuth redirect URIs stay stable across redeployments:

nexusai_domains_add(
  deploymentId: "7a2c91f0-…",
  domain:       "flixty.yourdomain.com"
)

Tip: Set up a custom domain before registering OAuth apps so your redirect URIs never change. Use https://flixty.yourdomain.com/auth/<platform>/callback as the redirect URI template.

Troubleshooting

OAuth redirects fail after deploy

This means BASE_URL is not set or points to the wrong URL. Check the current value with nexusai_deploy_status and redeploy with the correct public HTTPS URL. All OAuth callbacks are constructed from BASE_URL at runtime.

Posts fail for a specific platform

The platform credentials for that network are missing or incorrect. Check that the relevant env vars (X_CLIENT_ID, FB_APP_ID, etc.) are set via nexusai_deploy_status. Use nexusai_deploy_logs to see the exact OAuth error returned by the platform's API.

AI Assist not working

ANTHROPIC_API_KEY is not set or the key is invalid. Redeploy with a valid Anthropic API key. Verify it starts with sk-ant- and has not expired or been revoked in your Anthropic console.

Deployment stuck in "queued"

Check that your cloud provider credentials are properly configured in NEXUS AI. For GCP, ensure your service account has Cloud Run developer permissions. Use nexusai_deploy_logs to diagnose any build or startup failures — common causes are missing Node.js version compatibility or a package.json install failure.

Session errors after redeploy

If you redeploy without passing the original sessionSecret, a new secret is generated and all existing user sessions are invalidated. Always save and re-pass sessionSecret on subsequent deploys to maintain session continuity.

Wrapping up

Flixty on NEXUS AI gives you a fully self-hosted social media publishing stack — no third-party SaaS dependencies, no per-seat pricing, no data leaving your cloud. You control the OAuth tokens, the session data, and the posting schedule.

From here, explore attaching a custom domain for stable OAuth redirect URIs, enabling AI Assist with your Anthropic API key, or setting up a staging environment to test platform integrations before they go live.

Try it now: Head to nexusai.run and enable the NEXUS AI MCP connector in Claude to deploy Flixty with a single conversation in under 5 minutes.

NEXUS AI — AI-native cloud infrastructure · nexusai.run

I replaced my entire GitHub Actions deploy pipeline with one command

Saif Ali — Tue, 07 Apr 2026 16:56:29 +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.

I replaced my entire GitHub Actions deploy pipeline with one command

Saif Ali — Sat, 04 Apr 2026 11:14:28 +0000

My GitHub Actions deploy workflow was 87 lines of YAML.

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

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.

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

What I tried first

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.

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:

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

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.

The Complete Claude Code Tutorial: Build and Deploy an AI App in an Afternoon

Saif Ali — Sun, 29 Mar 2026 15:16:16 +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.

How to Deploy OpenClaw in NEXUS AI

Saif Ali — Sun, 29 Mar 2026 03:18:58 +0000

OpenClaw Personal AI Assistant Deployment

OpenClaw
is a lightweight AI coding gateway — Claude Code-compatible — exposes a secure token-authenticated endpoint. NEXUS AI makes deploying it entirely conversational: no YAML files, no Dockerfiles, no console wrestling. Just ask and it's live.

This guide walks you through deploying OpenClaw on NEXUS AI step by step — covering provider selection, environment setup, connecting your CLI, and optional advanced configuration. By the end you'll have a live gateway you can connect Claude Code or any compatible AI coding tool to.

What is OpenClaw?

OpenClaw (alpine/openclaw:latest) is a minimal, production-ready AI gateway service designed to work with Claude Code and compatible clients. It exposes a single authenticated endpoint on port 18789, identified by a gateway token that's either auto-generated or supplied by you at deploy time.

Once deployed, any Claude Code-compatible tool can point at your OpenClaw instance and authenticate with the token — giving you a self-hosted, cloud-native AI coding backend.

Prerequisites

A NEXUS AI account with at least one project configured The NEXUS AI MCP connector enabled in Claude — or API access to api.zollo.live/mcp A supported cloud provider account (for GCP, AWS, or Azure deployments) The OpenClaw CLI installed locally to connect after deployment Tip: You can also deploy OpenClaw entirely from within a Claude chat session if you have the NEXUS AI MCP connector enabled. No terminal required for the deploy itself.

Deploying OpenClaw — step by step

01 Choose your provider & environment NEXUS AI supports four deployment providers out of the box. For local development and testing, Docker is the fastest path. For production workloads, GCP Cloud Run offers the best cold-start performance and auto-scaling.

🐳 Docker Best for local dev & CI

☁️ GCP Cloud Run Serverless, auto-scales

⚡ AWS ECS Fargate Full AWS ecosystem

🔷 Azure Container Apps Enterprise & compliance

Environments map to: DEVELOPMENT for local testing, STAGING for pre-production validation, and PRODUCTION for live traffic.

02 Trigger the deployment Via the NEXUS AI MCP in Claude, call nexusai_deploy_openclaw with your provider and environment. A minimal invocation looks like this:

nexusai_deploy_openclaw(
  provider:    "gcp_cloud_run",
  environment: "PRODUCTION",
  name:        "openclaw-gateway"  // optional
)

If you don't supply a gatewayToken, one is securely auto-generated for you. You can also pass in Claude API credentials (claudeApiKey, claudeWebCookie) if your gateway requires them.

03 Save your deployment credentials After a successful deploy call, NEXUS AI returns:

Field Description Example id Deployment UUID 40693d12-… gatewayToken Auth token for CLI 6fb631a9d6… status Current state queued → running url Public endpoint Available once live Important: Copy your gatewayToken immediately — it's only returned once. Treat it like a password and store it in a secrets manager or your .env.

04 Monitor deployment status Deployments move from queued → provisioning → running. Check status anytime:

nexusai_deploy_status(
  deploymentId: "40693d12-0839-4821-aa3c-3621f12c74f4"
)

Once status shows running, the url field will be populated with your public endpoint.


- 05 Connect via the OpenClaw CLI
Point your local tooling at the gateway by setting two environment variables:

## Set your gateway token

shell
export OPENCLAW_GATEWAY_TOKEN="6fb631a9d6c66c45cb3f5890886b14dc"

Point CLI at your deployment URL
export OPENCLAW_GATEWAY_URL="https://your-deployment-url


## Verify the connection
openclaw status
You should see a confirmation that the gateway is reachable and authenticated. Claude Code and any compatible AI coding client will now route through your self-hosted OpenClaw instance.

* Tip: For persistent config, add these exports to your .zshrc / .bashrc, or use a .env file with direnv.
Advanced configuration
Custom gateway token
If you want a predictable, rotatable token instead of an auto-generated one, pass it explicitly at deploy time:

NEXUS AI MCP
nexusai_deploy_openclaw(
provider: "gcp_cloud_run",
environment: "PRODUCTION",
gatewayToken: "my-secure-token-from-vault"
)
Passing Claude credentials
If your OpenClaw instance needs to authenticate directly with Anthropic, you can pass your Claude session credentials at deploy time via claudeApiKey, claudeWebCookie, or claudeWebSessionKey. These are stored securely in NEXUS AI's secrets system and injected into the container at runtime.

Scaling your deployment

Once your OpenClaw gateway is live, you can scale it up instantly via NEXUS AI without redeploying:

nexusai_deploy_scale(
  deploymentId: "40693d12-…",
  replicas:     3
)```


## Custom domain
Attach a custom domain to your OpenClaw gateway for a clean, branded endpoint:
NEXUS AI MCP nexusai_domains_add( deploymentId: "40693d12-…", domain: "openclaw.yourdomain.com" )

Managing your OpenClaw deployment

NEXUS AI gives you full lifecycle control over every deployment. Here's a quick reference:

Action MCP Tool When to use Check status nexusai_deploy_status After deploying, or to verify health View logs nexusai_deploy_logs Debug connection or auth issues Stop gateway nexusai_deploy_stop Pause to save compute costs Restart nexusai_deploy_start After a stop, or after config changes Rollback nexusai_deploy_rollback Revert to a previous revision Delete nexusai_deploy_delete Permanently tear down

Troubleshooting

Gateway stuck in "queued" Check that your cloud provider credentials are properly configured in NEXUS AI. For GCP, ensure your service account has Cloud Run admin permissions. Use nexusai_deploy_logs to see what's happening inside the container.

CLI returns 401 Unauthorized
Double-check your OPENCLAW_GATEWAY_TOKEN environment variable. Tokens are case-sensitive. If you've lost the token, delete the deployment and redeploy with a custom gatewayToken you control.
Connection refused on port 18789
Verify the deployment status is running (not queued or stopped). Also confirm your OPENCLAW_GATEWAY_URL includes the correct port and protocol.

Wrapping up

OpenClaw on NEXUS AI gives you a fully managed, cloud-native AI coding gateway without any of the infrastructure overhead. You get auto-generated tokens, multi-cloud flexibility, instant scaling, and full lifecycle management — all through natural language or a single API call.

From here, you can explore connecting multiple Claude Code clients to the same gateway, attaching a custom domain, or setting up a staging → production promotion workflow entirely within NEXUS AI.

Try it now: Head to https://nexusai.run/. and enable the NEXUS AI MCP connector in Claude to deploy your first OpenClaw gateway in under 2 minutes.

AI #Deployment #OpenClaw

How to Deploy OpenClaw in NEXUS AI

Saif Ali — Sun, 29 Mar 2026 03:18:58 +0000

OpenClaw Personal AI Assistant Deployment

What is OpenClaw?

Once deployed, any Claude Code-compatible tool can point at your OpenClaw instance and authenticate with the token — giving you a self-hosted, cloud-native AI coding backend.

Prerequisites

Deploying OpenClaw — step by step

01 Choose your provider & environment NEXUS AI supports four deployment providers out of the box. For local development and testing, Docker is the fastest path. For production workloads, GCP Cloud Run offers the best cold-start performance and auto-scaling.

🐳 Docker Best for local dev & CI

☁️ GCP Cloud Run Serverless, auto-scales

⚡ AWS ECS Fargate Full AWS ecosystem

🔷 Azure Container Apps Enterprise & compliance

Environments map to: DEVELOPMENT for local testing, STAGING for pre-production validation, and PRODUCTION for live traffic.

02 Trigger the deployment Via the NEXUS AI MCP in Claude, call nexusai_deploy_openclaw with your provider and environment. A minimal invocation looks like this:

nexusai_deploy_openclaw(
  provider:    "gcp_cloud_run",
  environment: "PRODUCTION",
  name:        "openclaw-gateway"  // optional
)

If you don't supply a gatewayToken, one is securely auto-generated for you. You can also pass in Claude API credentials (claudeApiKey, claudeWebCookie) if your gateway requires them.

03 Save your deployment credentials After a successful deploy call, NEXUS AI returns:

04 Monitor deployment status Deployments move from queued → provisioning → running. Check status anytime:

nexusai_deploy_status(
  deploymentId: "40693d12-0839-4821-aa3c-3621f12c74f4"
)

Once status shows running, the url field will be populated with your public endpoint.


- 05 Connect via the OpenClaw CLI
Point your local tooling at the gateway by setting two environment variables:

## Set your gateway token

shell
export OPENCLAW_GATEWAY_TOKEN="6fb631a9d6c66c45cb3f5890886b14dc"

Point CLI at your deployment URL
export OPENCLAW_GATEWAY_URL="https://your-deployment-url


## Verify the connection
openclaw status
You should see a confirmation that the gateway is reachable and authenticated. Claude Code and any compatible AI coding client will now route through your self-hosted OpenClaw instance.

* Tip: For persistent config, add these exports to your .zshrc / .bashrc, or use a .env file with direnv.
Advanced configuration
Custom gateway token
If you want a predictable, rotatable token instead of an auto-generated one, pass it explicitly at deploy time:

Scaling your deployment

Once your OpenClaw gateway is live, you can scale it up instantly via NEXUS AI without redeploying:

nexusai_deploy_scale(
  deploymentId: "40693d12-…",
  replicas:     3
)```


## Custom domain
Attach a custom domain to your OpenClaw gateway for a clean, branded endpoint:
NEXUS AI MCP nexusai_domains_add( deploymentId: "40693d12-…", domain: "openclaw.yourdomain.com" )

Managing your OpenClaw deployment

NEXUS AI gives you full lifecycle control over every deployment. Here's a quick reference:

Troubleshooting

CLI returns 401 Unauthorized
Double-check your OPENCLAW_GATEWAY_TOKEN environment variable. Tokens are case-sensitive. If you've lost the token, delete the deployment and redeploy with a custom gatewayToken you control.
Connection refused on port 18789
Verify the deployment status is running (not queued or stopped). Also confirm your OPENCLAW_GATEWAY_URL includes the correct port and protocol.

Wrapping up

From here, you can explore connecting multiple Claude Code clients to the same gateway, attaching a custom domain, or setting up a staging → production promotion workflow entirely within NEXUS AI.

Try it now: Head to https://nexusai.run/. and enable the NEXUS AI MCP connector in Claude to deploy your first OpenClaw gateway in under 2 minutes.

AI #Deployment #OpenClaw

How to Deploy an AI App in Production: The Complete 2026 Guide

Saif Ali — Sun, 29 Mar 2026 02:25:42 +0000

Introduction

Deploying applications shouldn’t be this hard.

If you’ve ever tried to deploy an app, you’ve probably dealt with:

YAML configuration files

CI/CD pipelines

Infrastructure setup

Debugging deployment failures

What starts as “just a quick deploy” often turns into hours of frustration.

But what if you could deploy an app using AI — just by describing what you want?

That’s exactly what platforms like NEXUS AI are making possible.

In this guide, you’ll learn how to deploy apps with AI step by step, and why this is becoming the future of software development.

🤖 What is AI-Powered Deployment?

AI-powered deployment allows developers to:

Deploy applications using natural language prompts

Automate infrastructure setup

Eliminate manual DevOps work

Fix issues automatically using AI

Instead of writing complex configuration files, you simply tell the system what you want.

Example:

@nexus ai deploy my Node.js app to production
And the platform handles:

Build

Containerization

Deployment

Scaling

😩 Why Traditional Deployment is So Difficult
Before we dive into AI deployment, let’s understand the problem.

1. Too Many Tools

Developers often need:

Docker

Kubernetes

CI/CD pipelines

Cloud providers

2. YAML Complexity

Even a small mistake in YAML can break your deployment.

Example:

version: '3' services: app: build: . ports: - "3000:3000"
One indentation error → everything fails.

3. Debugging is Painful

Common issues:

Build failures

Environment mismatches

Missing dependencies

4. Requires DevOps Knowledge

Not every developer is a DevOps expert.

🚀 How AI Changes Deployment

AI removes complexity by handling everything automatically.

With NEXUS AI:

👉 You don’t configure infrastructure
👉 You don’t write YAML
👉 You don’t debug pipelines manually

Instead:

Prompt → AI → Live App

⚡ Step-by-Step: Deploy an App with AI

Let’s walk through how it works.

Step 1: Install NEXUS AI CLI

npm install -g nexusapp-cli

Step 2: Login

nexus auth login

Step 3: Deploy Your App

Now the magic happens.

@nexus deploy my app

Or:

@nexus deploy my Node.js API to production on gcp cloud provider

Step 4: AI Handles Everything

Behind the scenes, NEXUS AI:

Detects your app type

Builds your container

Configures infrastructure

Deploys to cloud

Makes your app live

Step 5: Your App is Live 🚀

In minutes, your app is deployed — no manual setup required.

💬 Bonus: AI Support & Troubleshooting

One of the biggest advantages is AI-powered support.

If something breaks:

@nexus fix my deployment issue

NEXUS AI will:

Diagnose the problem

Suggest fixes

Apply solutions

🔥 Real Use Cases

Indie Developers
Launch projects quickly without DevOps knowledge.
Startups
Reduce time to production.
Teams
Simplify deployment workflows.
Beginners
Deploy apps without learning complex tools.

🧠 Why This is the Future

We’ve already seen this shift:

Writing code → AI-assisted coding

Debugging → AI debugging

Now → Deployment is next

AI is turning complex workflows into simple interactions.

🚀 Key Benefits of NexusAI

Faster deployment

Less complexity

AI-powered troubleshooting

Works with prompts, code, or Git

No DevOps expertise required

💡 Pro Tips for Using AI Deployment

Be clear in your prompts

Use Git integration for real projects

Let AI handle infrastructure

Use CLI for faster workflows

🔮 Final Thoughts

The way we deploy applications is changing.

Instead of spending hours configuring infrastructure, developers can now:

👉 Describe what they want
👉 Let AI handle the rest

NexusAI is helping lead this shift toward AI-native development workflows.

👉 Get Started
Try NEXUS AII and deploy your first app in minutes:

👉 https://nexusai.run

Run your Docker container from AI prompts

Saif Ali — Thu, 26 Feb 2026 15:22:00 +0000

What is NEXUS AI?

If AI can write code and generate images, it can also manage infrastructure.

How it Works

With NEXUS AI, infrastructure becomes conversational...