Add a Deploy to NEXUS AI Button to Your GitHub Repo

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

Add a Deploy to NEXUS AI button to your GitHub README: step by step setup, nexus.json reference, link options, examples, and troubleshooting.

The Deploy to NEXUS AI button lets anyone who reads your README launch their own running copy of your app in a few clicks. You add one line of Markdown to your repository, and optionally a small nexus.json file that describes the databases and settings your app needs. Your users click the button, sign in to NEXUS AI, fill in any values you asked for, and get a live deployment with its own URL.

This guide is for repository owners. It walks through adding the button step by step, explains every nexus.json option, and shows complete examples you can copy.

What happens when someone clicks the button

1. The button opens https://nexusai.run/deploy?repo=<your repo URL>.
2. NEXUS AI reads your repository from GitHub and shows its name, description, and the settings from your nexus.json.
3. If the visitor is not signed in, they sign in or create an account and come straight back to the same page.
4. They choose a name and a deployment target, fill in the variables you marked as needed, and click Deploy.
5. NEXUS AI clones your repository, builds it, starts any databases you listed, and opens the deployment page with logs and the app URL.

Each deployment runs in the visitor's own NEXUS AI account and follows their plan's limits. You do not pay for their deployments, and you never see their secrets.

Before you start

• A public GitHub repository. The button reads repositories from GitHub without credentials, so private repositories are not supported.
• An app that NEXUS AI can build. Either a Dockerfile at the root of the repository (or of the folder you deploy), or a project NEXUS AI detects on its own, such as Node.js, Next.js, Vite, React, Vue, Python, PHP, Ruby, or a static site.
• An app that listens on 0.0.0.0, not only localhost, so the platform can reach it inside the container.

Step 1: Make sure your app deploys as is

Deploy your repository once from your own NEXUS AI account before adding the button. It is the quickest way to find a build problem before your users do.

If your repository has a Dockerfile at its root, NEXUS AI builds with it and uses the whole repository as the build context, exactly like docker build .. Build commands and start commands are ignored because your Dockerfile defines them. Two things to check:

• Declare the port with EXPOSE, for example EXPOSE 8080. NEXUS AI routes traffic to that port. If your Dockerfile serves the app with nginx, httpd, or Apache, NEXUS AI expects port 80.
• Run docker build . locally on a clean clone. If it fails there, it fails on NEXUS AI too.

If your repository has no Dockerfile, NEXUS AI detects the framework and generates one. For Node.js apps it runs your build script and your start script from package.json. Add a start script if you do not have one, or set startCommand in nexus.json (Step 2).

If your app lives in a subfolder (for example backend/ or apps/web/), set rootDir in nexus.json or add root-dir to the button link. NEXUS AI then builds only that folder.

Step 2: Add a nexus.json file (optional)

Without nexus.json, the button deploys your app with no extra services and no variables. Add nexus.json at the root of your repository when your app needs a database, a background worker, environment variables, or a specific folder or command.

Here is a complete example for a Node.js app with PostgreSQL, Redis, and a queue worker:

{
  "name": "Acme Tasks",
  "description": "Task manager with a Postgres database and a Redis job queue.",
  "services": ["postgres", "redis"],
  "worker": { "command": "node worker.js" },
  "buildCommand": "npm run build",
  "startCommand": "npm start",
  "env": {
    "NODE_ENV": { "value": "production" },
    "SESSION_SECRET": { "generator": "secret" },
    "STRIPE_SECRET_KEY": { "required": true, "description": "Your Stripe secret key (sk_live_... or sk_test_...)" },
    "SENTRY_DSN": { "description": "Optional: error reporting" }
  }
}

nexus.json reference

Commands must be a single line. The file must be valid JSON and smaller than 64 KB.

Environment variables

Each key in env is a variable name in capital letters, digits, and underscores (for example API_KEY). Each value is an object that says where the value comes from:

Use generator for values your app needs but no person has to know, such as session or JWT signing secrets. Use required for anything only the user can supply, such as their own API keys. Never put a real secret in value: nexus.json is public, like the rest of your repository.

Connection variables from services

When you list a service, NEXUS AI starts it on a private network with your app and sets connection variables for you. Do not declare these yourself.

Read DATABASE_URL, REDIS_URL, or MONGO_URI in your app. They are the most portable names across deployment targets. If your app expects a different name (for example POSTGRES_URL), have your code fall back to DATABASE_URL when that name is not set. That is a one-line change and it keeps the button working.

Step 3: Add the button to your README

Paste this into your README.md, replacing OWNER/REPO with your repository:

[![Deploy to NEXUS AI](https://nexusai.run/deploy-button.svg)](https://nexusai.run/deploy?repo=https://github.com/OWNER/REPO)

If your README uses HTML, use this instead:

<a href="https://nexusai.run/deploy?repo=https://github.com/OWNER/REPO">
  <img src="https://nexusai.run/deploy-button.svg" alt="Deploy to NEXUS AI" height="36">
</a>

Link options

Add these to the link as query parameters:

Example with both options:

[![Deploy to NEXUS AI](https://nexusai.run/deploy-button.svg)](https://nexusai.run/deploy?repo=https://github.com/OWNER/REPO&branch=stable&root-dir=apps/api)

Step 4: Test the button yourself

1. Commit nexus.json and the README change, and push them to GitHub.
2. Open your repository page on GitHub and click the button.
3. Check that the deploy page shows your repository and your variables. If nexus.json has a mistake, the page tells you exactly which field is wrong.
4. Deploy, then watch the build logs on the deployment page until the status is Running and the app URL loads.

NEXUS AI caches what it reads from GitHub for up to 10 minutes. If you just changed nexus.json and the deploy page still shows the old settings, wait a few minutes and reload.

Deployment targets

Users choose where their copy runs. The NEXUS AI runtime is always available, including on the Free plan. If the user's organization has connected a cloud account, they can also pick AWS App Runner, Google Cloud Run, or Azure Container Apps.

On cloud targets, postgres and mysql are created as managed databases. redis, mongodb, and worker run only on the NEXUS AI runtime. When your nexus.json lists any of them, the form offers only the NEXUS AI runtime, so users never start a deploy that cannot work.

Examples

A single-container app with a Dockerfile and no database

Good for tools that keep their data in SQLite or files, and for demos on the Free plan, which allows one deployment at a time:

{
  "name": "My AI Gateway",
  "env": {
    "STORAGE_TYPE": { "value": "sqlite" },
    "ADMIN_KEY": { "required": true, "description": "Key that protects the admin dashboard. Keep it somewhere safe." },
    "OPENAI_API_KEY": { "description": "Optional: add at least one provider key now or later in the dashboard" }
  }
}

Data in SQLite or on the container's own disk is lost when the container is recreated, for example on a redeploy. That is fine for trying an app out. For long-lived data, list a database in services.

A monorepo with separate frontend and API

Add one button per app and point each at its folder:

[![Deploy the API](https://nexusai.run/deploy-button.svg)](https://nexusai.run/deploy?repo=https://github.com/OWNER/REPO&root-dir=api)
[![Deploy the web app](https://nexusai.run/deploy-button.svg)](https://nexusai.run/deploy?repo=https://github.com/OWNER/REPO&root-dir=web)

nexus.json is always read from the repository root, so its services and env apply to both buttons. If the two apps need different settings, keep nexus.json minimal and let each app read its own variables.

Troubleshooting

"This repository's nexus.json has a problem: ..." The message names the field. Common causes are a trailing comma (invalid JSON), a service name other than postgres, mysql, mongodb, or redis, a lowercase variable name, or a command split over several lines.

"STRIPE_SECRET_KEY is required" A variable marked required was left empty. The user needs to fill it in. If the app can start without it, remove "required": true.

The build fails with "No start script found" Your Node.js app has no start script and no Dockerfile. Add a start script to package.json or set startCommand in nexus.json.

The build fails but works on my machine Clone the repository fresh and run docker build . (with a Dockerfile) or your install and build commands. Files ignored by .gitignore, or excluded by .dockerignore but needed during the build, are the usual cause.

The deployment is Running but the URL does not load, or the health check fails Make sure the app listens on 0.0.0.0 and on the port from your EXPOSE line (or the PORT variable for generated builds). An app bound to 127.0.0.1 cannot be reached from outside its container.

The app starts but cannot connect to its database Read DATABASE_URL (or REDIS_URL, MONGO_URI) rather than a hard-coded host such as localhost. The database runs in its own container on a private network.

"GitHub is rate limiting requests right now" Wait a few minutes and try again.

The deploy page says the repository cannot be read Check that the repository is public and that the repo link points to https://github.com/OWNER/REPO, not to a file or branch page.

Frequently asked questions

Do my users need a NEXUS AI account?

Yes. The deployment runs in their own account. If they are not signed in, the button page sends them to sign in or register and brings them back to finish the deploy.

Does the button work on the Free plan?

Yes. Free accounts deploy to the NEXUS AI runtime, with the Free plan's limits: one deployment at a time and an automatic expiry for test deployments. The deployment page shows when it expires.

Can I use the button with a private repository?

No. The button only reads public GitHub repositories. Private repositories can still be deployed from the NEXUS AI dashboard or CLI after connecting GitHub.

Is nexus.json required?

No. Without it, NEXUS AI deploys your app using your Dockerfile or its framework detection, with no databases and no extra variables.

Does NEXUS AI run anything from nexus.json on its servers?

No. nexus.json is read as data only. Commands in it run inside the user's build and app containers, the same way your Dockerfile or package.json scripts do.

Will users get updates when I push new commits?

Each click deploys your repository as it is at that moment. Existing deployments do not change when you push. A user who wants a newer version can redeploy.

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