Clone step fails with 'Permission denied (publickey)'

This only happens on the paste-a-URL path with an SSH URL. The simplest fix is to connect your GitHub account instead - click Connect GitHub in the form, authorize CtrlOps, and pick the repo from the list. Private repos then clone with no key setup at all. If you'd rather stay on the SSH URL, add the server's public key as a deploy key on the GitHub repo. You can grab the server's key from the SSH Management tab.

My repository doesn't appear in the dropdown

If the repo belongs to an organization, an org owner may need to approve CtrlOps' access before it shows up. If you created the repo after connecting, reconnect your GitHub account to refresh the list.

`npm install` step fails with 'EACCES' or permission errors

The user CtrlOps deploys as doesn't own the target folder. Pick a folder under `/home/ /`, where the user has write access, instead of `/var/www` or `/opt`.

Build step fails with 'JavaScript heap out of memory'

The build is hitting the default Node memory limit. Add this env variable in Card 4 of the form: `NODE_OPTIONS=--max-old-space-size=4096` (adjust the number to fit your server's RAM).

Start step succeeds but the app isn't reachable

Your app may be listening on `localhost` instead of `0.0.0.0`. Check your code's `app.listen()` call. Or, the firewall may be blocking the port, see the AI Terminal: `sudo ufw status`.

SSL step fails with 'unauthorized' or 'DNS problem'

DNS isn't pointing to this server, or ports 80/443 are blocked.

My app crashed after a deploy and won't restart

Open the AI Terminal and run `pm2 logs `. The crash reason is almost always in the last few lines. Common causes: missing env variable, port already in use, database not reachable.

The technology badge says 'Unknown' for my app folder

CtrlOps detects the tech from `package.json` dependencies (`next` for Next.js, `react` for React, `express` for Node.js). If your stack uses something else, the badge will be "Unknown". The Folder Details page still works the same way.

Deploy Node.js Apps from GitHub - No CI/CD

Connect your GitHub account, pick a repo and branch, and deploy Node.js, React, or Next.js apps to your Linux server. No CI/CD setup required.

CtrlOps takes a GitHub repository and turns it into a running app on your server. Connect your GitHub account once, pick a repo and branch from the list, choose a Node version, set your env variables, optionally add a domain with HTTPS, and click Create. CtrlOps clones the repo, installs dependencies, builds, starts the app under PM2, configures Nginx, and issues an SSL certificate. You watch the whole thing happen in a live progress modal. For a full hands-on walkthrough - the manual 13-step process versus one-click deployment - see How to Deploy a Node.js App on a Linux VPS in 5 Minutes.

Deploy apps from GitHub, end to end

Connect your GitHub account once, then pick the repo and branch from a dropdown. Private repos included, no key setup.
Deploy a Node.js, React, Next.js, or static "build folder" app from a GitHub repo.
Pick the Node.js version (and install it on the fly if it's missing).
Set environment variables one by one, or paste a whole .env block at once.
Add one or more domains, with optional automatic SSL via certbot.
Watch deployment progress live with command output and step status.
Edit the app's .env later from the Folder Details page.

Before you start

Requirement	Why
An active connection to a Linux server	The deploy runs on whichever server you opened
A GitHub repository for the app	Connect your GitHub account and pick it from the list - this covers private repos with no extra setup. A public repo URL also works without connecting.
Domain DNS already pointing at the server (only if you'll use SSL)	Required so certbot can issue the certificate - a quick DNS record lookup confirms the A record before you deploy
PM2, Node, and Nginx	CtrlOps installs whatever's missing as part of the deploy

Open the Add Application form

You can launch the form from a few places.

From the Deployments tab

Open app → Click your server → Deployments tab → Click Add Application

The Deployments tab is the dedicated home for your apps. This is the most common path.

Open app → Click your server → File Manager tab → Click Add Application (top toolbar)

The same form, reached from wherever you happen to be.

From an existing app folder

File Manager → Click into an app folder → The Folder Details page opens

If the folder has a package.json, you'll see the technology badge (Next.js, React, Node.js) at the top, plus the Files and Environment Variables tabs. To add a new app, use the toolbar button above.

Set up your first deployment

The form is split into five cards. Fill them in top to bottom.

Basic Information

Field	What to enter
Application Name	A friendly name like `My Node.js App`. The folder name preview appears below the field.
Environment	Development, Staging, or Production. Pick whichever fits.

GitHub Repository

Two ways to point CtrlOps at your code.

Connect your GitHub account (recommended)

Click Connect GitHub and authorize CtrlOps in the browser that opens. Your repositories load into a dropdown - pick the one you want, then pick the branch from a second dropdown.

Private repos are included automatically. There's no key or token to set up.

Connecting is a one-time step. Every deploy after this one reuses the connection, so you go straight to picking a repo.

Paste a repository URL

Still supported if you'd rather not connect. Toggle between HTTPS and SSH, then paste the repo URL.

Two things to know about this path:

There's no branch picker. CtrlOps deploys the repo's default branch.
Private repos over SSH still need a deploy key. Add the server's public key to the repo on GitHub first, which you can grab from the SSH Management tab. Over HTTPS, only public repos will clone.

Connecting your GitHub account removes the deploy-key step entirely and is the only way to choose a branch. The deploy-key requirement applies only to the paste-a-URL path with an SSH URL.

Node.js Version

Pick the Node version from the dropdown. Versions already installed on the server show a green checkmark. Versions not yet installed show a download icon, CtrlOps will install them as part of the deploy.

Build Configuration

Field	What to enter
Application Type	Node.js, React, Next.js, or Build Folder
Install Command	Defaults to `npm install`. Change to `yarn install` or `pnpm install` if needed.
Build Command	Auto-fills with `npm run build` for React and Next.js. Leave empty for plain Node.js.
Start Command	Defaults to `npm start`. For static React, use `serve -s build -l <port>`.
Local Redis Server Needed	Toggle on for Node.js apps that need Redis on the same machine

Environment Variables

Two ways to add them.

One at a time

Click Add Environment Variable. A new row appears with two inputs: Key and Value. Repeat for each variable.

Paste a whole .env block

Click Bulk Paste Environment Variables. A modal opens titled Paste Environment Variables. Paste the contents of your local .env file:

DATABASE_URL=postgres://user:pass@host:5432/db
API_KEY=sk_live_abc123
# Comments are fine, lines starting with # are ignored

Confirm. All variables are added to the list at once.

Quotes (" and ') and special characters in values are fully supported.

Domains (optional)

Skip this card entirely if you don't need a domain yet, you can deploy and add one later.

Field	What to enter
Setup SSL certificates for domains (using Certbot)	Toggle on to enable HTTPS automatically
Port	The port your app listens on, e.g. `3000`. Required when SSL is enabled.
Add Domain	Click to add a domain row. Enter a domain like `yoursite.com`. Click again to add more.

When SSL is on, adding yoursite.com automatically also covers www.yoursite.com. You don't need to add both.

For SSL to succeed, your domain's DNS A record must already point to this server's public IP. If DNS isn't ready yet, deploy without SSL first, then add it once DNS resolves.

Click Create

CtrlOps closes the form and opens the Deployment Progress modal. You'll see each step in a checklist (clone, install, build, start, configure Nginx, issue SSL) along with live terminal output.

Watch the deployment

Each step turns green when it succeeds, red if it fails. The terminal area shows exactly what the server is doing. When the last step finishes, you have a running app.

Edit environment variables later

Once the app is deployed, you can update its .env from the Folder Details page.

Open the app folder

File Manager → Click into your app folder

The Folder Details page opens, showing a technology badge (Next.js, React, Node.js) and version, plus two tabs.

Switch to the Environment Variables tab

Existing variables are listed with key on the left and value on the right. If there are none yet, you'll see "No environment variables found".

Add a new variable

Scroll past the list to the form at the bottom. Two inputs side by side:

Field	What to enter
Variable Name	The key, e.g. `API_KEY`
Value	The value, e.g. `sk_live_abc123`

Click Add → The variable appears in the list above

Remove a variable

Click the red trash icon at the right of the row. The variable is removed from the .env file immediately.

Changing env variables doesn't restart the app automatically. After your edits, open the AI Terminal and run pm2 restart <app-name> to pick up the new values.

Re-deploy or pull the latest code

There's no built-in re-deploy button right now. To pull new commits and restart:

cd /home/<user>/<app-folder>
git pull
npm install
npm run build       # only if you have a build step
pm2 restart <app-name>

You can also wrap this in a Script so it's one click next time.

Common PM2 commands

PM2 is the process manager that keeps your app running. Use these in the AI Terminal.

You don't need pm2 logs to read your app's output. Every PM2 process's out and error logs are already listed in the Logs tab, where you can search them, tail them live, or download them.

Command	What it does
`pm2 list`	See all your running apps and their status
`pm2 logs <app-name>`	Tail the live logs for an app
`pm2 restart <app-name>`	Restart the app, picks up new env vars and code
`pm2 stop <app-name>`	Stop the app without removing it
`pm2 start <app-name>`	Start a stopped app
`pm2 delete <app-name>`	Remove the app from PM2 entirely

Tips

Use Bulk Paste Environment Variables to copy from your local .env in one go. It saves a lot of clicking on a real-world app.

Deploy without SSL first if you're not sure DNS is ready. You can run certbot afterwards from the AI Terminal.

Watch the deployment progress modal end to end the first time. If something goes wrong, the failing step's terminal output usually points straight to the cause.

Application Deployment