How to Deploy a Node.js App to Sealos in 5 Minutes

Want to deploy a Node.js service without writing Kubernetes YAML or building a custom release pipeline by hand? This Node.js deployment guide shows how to take a GitHub repo, run the Sealos AI deployment skill, and publish a working service on Sealos with a public HTTPS URL.

With the Sealos skill, your AI agent can inspect the project, detect that it is a Node.js service, prepare missing deployment artifacts, build or reuse a container image, generate a Sealos template, and deploy the service to Sealos Cloud.

By the end, you will have:

• A Node.js service running on Sealos
• A public HTTPS URL
• A deployment state saved under .sealos/
• A repeatable path for future updates and Node.js production deployment prep
• Follow-up paths for Node.js + PostgreSQL and the Node.js production deployment checklist

Prerequisites

You need:

• A GitHub repository containing a working Node.js service
• A Sealos Cloud account
• Codex, Codex App, or Claude Code with the Sealos plugin installed
• A container registry path if the service needs to be built, such as GHCR or Docker Hub
• Optional but useful: Docker, GitHub CLI, kubectl, and Node.js available locally

One Sealos plugin installs deploy, database, S3, canvas, app-builder, and supporting cloud-native skills from root skills/**.

If you are using Codex, install the Sealos plugin with the native Codex marketplace flow:

codex plugin marketplace add labring/sealos-skills
codex plugin add sealos@sealos

For Codex compatibility or local testing, use:

npx plugins add https://github.com/labring/sealos-skills --target codex

If you are using Claude Code, install the same Sealos plugin with the native Claude Code marketplace flow:

claude plugin marketplace add labring/sealos-skills
claude plugin install sealos@sealos

For Claude Code compatibility, use:

npx plugins add https://github.com/labring/sealos-skills --target claude-code

After installation:

• In Codex CLI, use $sealos
• In Codex App, click + -> Plugins -> Sealos
• In Claude Code, use /sealos

What the Sealos skill does for a Node.js service

When you ask Sealos to deploy a GitHub repo, the deploy skill runs one stateful pipeline:

1. Phase 0 preflight checks the project path, useful local tools, Sealos authentication, workspace access, and any Docker or registry readiness that your chosen deploy path needs.
2. Phase 1 assessment inspects the service and writes .sealos/analysis.json so you can see what Sealos inferred before anything is deployed.
3. Phase 2 image detection looks for a reusable linux/amd64 image in registries, compose files, CI workflows, or project docs.
4. Phase 3 Dockerfile generation or reuse prepares a container path only when the project needs one.
5. Phase 4 build and push runs only when Sealos needs a new image. It records the result in .sealos/build/build-result.json.
6. Phase 5 template generation writes .sealos/template/index.yaml, the Sealos resource plan for the app, service, ingress, environment variables, image pull Secret references, and database resources when applicable.
7. Phase 5.5 configuration asks for missing required values and lets you review deployment settings.
8. Phase 6 deploy submits the generated template through Sealos and checks resource readiness.
9. Phase 6.5 Runtime Truth Pass verifies the live service before the deployment is accepted.

For a typical Node.js service, it detects:

• Runtime: Node.js
• Server entrypoint: server.js, app.js, dist/server.js, or the file behind npm start
• Package manager: npm, pnpm, yarn, or bun
• Build command, usually absent for plain JavaScript or npm run build for TypeScript and bundled services
• Runtime command, usually npm start
• Required environment variables from .env.example, source code, and config files
• Runtime port from PORT, a documented default, or the generated template
• Health endpoint such as /healthz or /health

Step 1: Start with a deployable GitHub repo

Your repository should include a normal Node.js service structure:

my-nodejs-service/
├── package.json
├── server.js, app.js, or src/server.ts
├── public/ or routes/ if the service needs them
└── .env.example

Your package.json should include a production start command:

{
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  }
}

For a TypeScript service, a build step is expected:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

The exact framework can differ. Express, Fastify, Hono on Node.js, NestJS, and custom HTTP servers all work when the service starts reliably in a container.

Before deploying, verify the actual scripts in package.json:

npm install
npm start

Use npm run build before npm start when the service compiles TypeScript or bundles server code.

Node.js package script and entrypoint review for server.js app.js or dist/server.js

Your service should read PORT, bind to 0.0.0.0, and expose a lightweight health endpoint:

import express from 'express';
 
const app = express();
const port = Number(process.env.PORT || 3000);
 
app.get('/healthz', (_req, res) => {
  res.json({ ok: true });
});
 
app.listen(port, '0.0.0.0', () => {
  console.log(`Node.js service listening on ${port}`);
});

Step 2: Ask Sealos to deploy the repo

In Codex CLI, run:

$sealos deploy https://github.com/<owner>/<repo>

In Claude Code, run:

/sealos deploy https://github.com/<owner>/<repo>

If you are already inside the repo, you can say:

$sealos deploy this Node.js service to Sealos Cloud

The skill starts with preflight checks. It verifies the project path, checks useful tools, and confirms Sealos authentication.

Preflight also checks the selected Sealos workspace and permissions to create resources. Docker, buildx, GHCR, and registry warnings appear when the service needs a local build or private image push. A repo that already has a usable public linux/amd64 image may skip that build path.

Step 3: Review the project assessment

The skill analyzes the repo and prints a readiness summary.

For a healthy Node.js service, you should see something like:

Runtime: Node.js
Entrypoint: server.js or dist/server.js
Package manager: npm
Build command: npm run build, or none
Runtime command: npm start
Port: from PORT, default 3000
Bind address: 0.0.0.0
Health endpoint: /healthz
Database: none detected
Score: good
Decision: continue

This is the first important checkpoint. It tells you whether Sealos understands your repo as a deployable service.

If the score is low, fix the project before continuing. Common reasons include:

• Missing start script
• npm start launches a local dev watcher instead of a production process
• The service binds only to localhost
• The service ignores PORT
• No identifiable HTTP server or health endpoint
• Required env vars are missing from .env.example

Node.js service assessment summary for Sealos deployment

Step 4: Let Sealos prepare the container

If your repo already has a valid Dockerfile, Sealos can reuse it.

If it needs to generate one, the Node.js production pattern is a dependency install step, an optional build step, and a runtime command that starts exactly one foreground service process.

A generated runtime should make the container start command explicit:

Runtime command: npm start
Entrypoint: server.js, app.js, or dist/server.js
Listen address: 0.0.0.0
Container port: 3000
Health endpoint: /healthz

Review .sealos/template/index.yaml before deploy. The exposed container port should match the port your service reads from PORT.

Node.js generated container start command and template port summary

Step 5: Build and push the image

When Sealos needs a new image, it builds and pushes a linux/amd64 image to the configured registry.

Check that the build uses production dependencies and the right command order:

npm ci
npm run build   # TypeScript or bundled services only
npm start       # runtime command

The build result is recorded under .sealos/build/build-result.json when a local build path is used.

Step 6: Configure environment variables

Use placeholder values in .env.example and real values in Sealos configuration.

Typical Node.js service env vars include:

NODE_ENV=production
PORT=3000
LOG_LEVEL=info
API_BASE_URL=https://example.com

Keep tokens, passwords, private registry credentials, and database URLs out of committed files.

Node.js redacted environment variable configuration

Step 7: Deploy to Sealos Cloud

After configuration, Sealos applies the generated template and waits for resources to become ready.

Review:

• The generated app uses the expected image
• The Service exposes the same container port as PORT
• The Ingress gives you the expected public URL
• Env vars are present on the running app
• Rollout status reaches ready

Step 8: Verify the deployment

Run Runtime Truth Pass against the live service.

For a Node.js service, the acceptance evidence should include:

• Public URL smoke check returns a non-5xx response
• /healthz or /health returns healthy JSON or text
• Service startup logs show the expected port and no crash loop
• Request logs show the live smoke traffic
• Resource footprint is reasonable for the service size
• .sealos/state.json records the accepted app name, namespace, image, App URL, and bounded history

Example smoke checks:

curl -fsS https://<your-app-url>/healthz
curl -fsS https://<your-app-url>/

What changed in your repo

A successful Sealos deployment usually adds or updates:

.sealos/
├── analysis.json
├── state.json
├── build/
│   └── build-result.json
└── template/
    └── index.yaml

Use these files as deployment memory. .sealos/analysis.json explains what the plugin inferred, .sealos/template/index.yaml shows the generated app/service/ingress plan, and .sealos/state.json records the last accepted runtime truth.

Common errors and fixes

Next steps

• Add PostgreSQL with Node.js + PostgreSQL Deployment Guide on Sealos
• Prepare launch readiness with Complete Production Deployment Checklist for Node.js on Sealos
• Open Sealos Skills when you want the repeatable plugin workflow and command entrypoints