Headless App Deployment From CI, the CLI, APIs, and AI Agents

By NEXUS AI Team · Contact: nexusai.run/contact

Deploy and run apps with no dashboard: from GitHub Actions, the nexus CLI, the REST API, or an AI agent over MCP, using scoped, expiring access tokens.

What headless deployment means

Headless deployment is shipping and operating an app entirely through code: a pipeline step, a script, or an agent's tool call builds the app, deploys it, reads its logs, scales it, and rolls it back. On NEXUS AI the CLI, the REST API, and the MCP server all drive the same platform, so anything a person can do in the dashboard, automation can do too.

Scoped tokens for machines

Create an nxk_ access token for each pipeline or tool with only the scopes it needs, such as deployments:create, deployments:read, and deployments:logs, and an expiry like 90 days. Set it as NEXUSAI_TOKEN and the CLI uses it with no login step. List tokens that have not been used recently and revoke any of them with one command.

Deploy from CI/CD

In GitHub Actions, GitLab CI, or any pipeline, install the nexus CLI and run nexus deploy redeploy with --wait after your tests pass. It rebuilds the deployment in place, keeps its database and secrets, and waits until the app is running or has failed. With no CI at all, connect the repository and every push to an allowed branch deploys automatically.

The REST API

The CLI is a client of the NEXUS AI REST API, and your own tools can call the same endpoints with a Bearer access token: start a source deployment from a Git repository or an uploaded ZIP, poll its status, read logs, and manage secrets, domains, and databases.

AI agents over MCP

Claude, Cursor, Codex, and other MCP clients connect to https://mcp.nexusai.run/mcp with OAuth and get 74 tools. An agent can push generated files to the AI Builder with nexusai_builder_push for a live preview, pull back your edits with nexusai_builder_pull, deploy a Git repository with nexusai_deploy_source, and then watch logs, scale, and roll back.

Build with AI in the terminal

The nexus builder commands work on the same AI Builder project as the browser: chat with the builder, pull the files to edit locally, push your edits back, run syntax checks, ask the AI to fix errors, list and restore checkpoints, and deploy the current snapshot.

Ship without the dashboard

Redeploy after tests pass

The job rebuilds the existing deployment in place and waits for the result.

Create an access token with deployments:create and deployments:read.
Save it as the NEXUSAI_TOKEN repository secret.
Add the workflow; it runs after your test job.

name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: npm install -g nexusapp-cli@latest
      - run: nexus deploy redeploy shop --yes --wait
        env:
          NEXUSAI_TOKEN: ${{ secrets.NEXUSAI_TOKEN }}

redeploy keeps the deployment's attached database, volumes, and secrets. Use nexus deploy source for the first deploy.

CLI authentication · Manage deployments

Create a token for a pipeline

Give each machine its own token with the smallest scopes and an expiry.

Create the token and copy the nxk_ value it prints once.
Store it in your CI secret store as NEXUSAI_TOKEN.
Review and revoke tokens that are no longer used.

nexus token create \
  --name github-actions \
  --scopes deployments:create,deployments:read,deployments:logs \
  --expires 90d

nexus token list --unused-since 30
nexus token revoke <token-id> --yes

With NEXUSAI_TOKEN set, every nexus command authenticates without nexus auth login.

Access tokens

Start a deployment from your own tooling

The same endpoint the CLI calls, with a Bearer access token.

Send the repository and a name.
Read the deployment ID from the response.
Poll the deployment until its status is RUNNING or FAILED.

curl -X POST https://nexusai.run/api/gpt/deploy/source \
  -H "Authorization: Bearer $NEXUSAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceType":"repo","repoUrl":"https://github.com/you/shop","name":"shop"}'

curl https://nexusai.run/api/deployments/<deployment-id> \
  -H "Authorization: Bearer $NEXUSAI_TOKEN"

The token needs deployments:create to start a deployment and deployments:read to poll it.

Deployments API · API authentication

Edit an AI-built app locally, then deploy it

Pull the Builder project, edit it in your own editor, let the AI fix what breaks, and deploy the snapshot.

Pull the files of an AI Builder project.
Edit locally, push the changes back, and run the checks.
Deploy the current snapshot.

nexus builder pull -p <project-id> --out ./app
# edit files in ./app
nexus builder push -p <project-id> --from ./app
nexus builder check -p <project-id>
nexus builder fix -p <project-id>
nexus builder deploy -p <project-id> --name app --provider docker

Every push creates a checkpoint; nexus builder versions lists them and nexus builder revert restores one.

AI Builder documentation

Let an agent preview, then ship

Connect Claude, Cursor, or Codex to https://mcp.nexusai.run/mcp and approve the scopes it needs.

nexusai_builder_push sends the generated files to the AI Builder and returns a preview URL.
nexusai_builder_pull brings back any edits made in the browser.
After the code is in Git, nexusai_deploy_source deploys it, and nexusai_deploy_status and nexusai_deploy_logs verify it.

Build a support-ticket app in my NEXUS AI project and push it to the AI Builder so I can review the preview. After I approve it and push it to GitHub, deploy the repository with PostgreSQL and show me the status and the last build logs.

Pushing to the Builder creates a checkpoint, not a deployment. Deploying needs the deployments:create scope.

MCP deployment platform · Builder handoff

How it works

Create an access token with the scopes the pipeline or tool needs.
Store it as NEXUSAI_TOKEN in CI, or connect an AI agent to the MCP server with OAuth.
Deploy with nexus deploy, the REST API, or an MCP tool call.
Read status and logs the same way, and roll back if needed.

Headless deployment paths compared

Path	Best for	Authentication	What it deploys
Push to deploy	Every push to an allowed branch, with no CI	Connected repository with signed webhooks	The pushed commit
CI pipeline	Deploying after tests pass	NEXUSAI_TOKEN access token	A redeploy in place or a new source deploy
nexus CLI in scripts	Scripts and local automation	nexus auth login or NEXUSAI_TOKEN	Git repositories and container images
REST API	Your own platform or internal tools	Bearer access token	Git repositories and uploaded ZIPs
MCP server	AI agents in Claude, Cursor, and Codex	OAuth with approved scopes	Git repositories, images, and Builder previews
Terminal AI Builder	Building with AI without a browser	nexus auth login or NEXUSAI_TOKEN	The current Builder snapshot

Frequently asked questions

What is headless app deployment?

Deploying and operating an app entirely through code, with no one clicking through a web dashboard. A CI pipeline, a script, or an AI agent builds the app, deploys it, reads its logs, and rolls it back through a CLI, an API, or MCP tool calls.

How do I deploy from GitHub Actions?

Create an access token with deployments:create and deployments:read, save it as the NEXUSAI_TOKEN secret, then add a step that installs nexusapp-cli and runs nexus deploy redeploy <name> --yes --wait. The step waits until the deployment is running or has failed.

How does a CI pipeline authenticate?

With an nxk_ access token in the NEXUSAI_TOKEN environment variable. Create one with nexus token create, choose only the scopes the pipeline needs, and set an expiry. Tokens can be listed by last use and revoked at any time.

Can I deploy on every git push without CI?

Yes. Connect the repository to NEXUS AI and enable auto-deploy: pushes to allowed branches create a deployment after the webhook signature is verified.

Is there a REST API?

Yes. The CLI is built on it. Call it with a Bearer access token to start source deployments from a Git repository or an uploaded ZIP, read status and logs, and manage secrets, domains, and databases.

Can an AI agent deploy without the dashboard?

Yes. Connect Claude, Cursor, Codex, or another MCP client to https://mcp.nexusai.run/mcp with OAuth. The agent can preview generated files in the AI Builder, deploy a Git repository or container image, and then read logs, scale, and roll back.

What do nexusai_builder_push and nexusai_builder_pull do?

nexusai_builder_push writes a generated file set into a project's AI Builder session as a restorable checkpoint and returns a preview URL. nexusai_builder_pull returns the latest files, including edits made in the browser, so the agent continues from what you changed.

Can I build an app with AI without opening a browser?

Yes. The nexus builder commands chat with the same AI Builder project, pull files for local editing, push edits back, run checks, ask the AI to fix errors, restore checkpoints, and deploy the current snapshot.

Is headless deployment secure?

Each machine gets its own token or OAuth grant with only the scopes it needs, and tokens can expire and be revoked. MCP tools that change or delete data are marked destructive so clients can ask first. Deploys, restores, database queries, schema fixes, and managed database changes are recorded in the audit log.

About NEXUS AI

NEXUS AI is an agentic AI app builder and full-stack deployment platform. Explore the AI App Builder, learn more on the About page, read the documentation, or contact the team through nexusai.run/contact.

Start for free · Read the documentation · About NEXUS AI · Contact