Running Node.js on shared cPanel servers has historically meant Passenger through the “Setup Node.js App” interface, which works but ties the application to the Apache process model and to the Node versions EasyApache ships. cPanel & WHM 138, released in July 2026, introduced the AI-Native Node.js Toolkit: each application runs in its own Podman container, is reachable on a subdomain that the toolkit configures, and can be scaffolded or adjusted with the AI assistant. This tutorial deploys a small Express application from a Git repository, sets environment variables, and shows where to look when it does not start.
Table of Contents
Short answer: Enable the toolkit in WHM → Tweak Settings and the account’s feature list, then in cPanel → Software → Node.js Toolkit choose Create Application, pick a Node version, point it at a Git repository or a directory containing package.json, and assign a subdomain. The toolkit builds a Podman image, starts the container as the account user and proxies the subdomain to it; add secrets as environment variables in the app settings rather than committing a .env file. The same steps run from the shell with uapi NodejsToolkit create_application and deploy_application.
What the toolkit provides
The toolkit builds a container image for the application from the account’s files or a repository, runs it as the account user under Podman with resource limits, and proxies traffic from a subdomain such as app.example.com to the container’s port. Node versions are pulled as images, so the choice is independent of EasyApache. Logs, restarts and environment variables are managed from cPanel → Software → Node.js Toolkit, and the same operations are available through UAPI for automation. The “AI-native” part is optional: Ask AI can generate a starter project or explain a failing build, but nothing requires it.
Requirements on the server side: cPanel 138 or later, Podman installed (the toolkit installs it on first use on AlmaLinux 9 and 10 and Ubuntu 24.04), and enough disk for images, which live under each user’s home directory. CloudLinux users should confirm that CageFS and LVE limits are compatible with rootless Podman on their version before enabling it widely.
Enable the toolkit
Enable it in WHM → Server Configuration → Tweak Settings under the application section, then add it to a feature list:
whmapi1 get_tweaksetting --output=json | grep -i nodejs_toolkit
whmapi1 update_featurelist featurelist=default nodejs_toolkit=1Confirm the exact key and feature names on your build with the first command. When enabled, the first visit to the toolkit as a user triggers the Podman setup for that account, which takes a minute.
Deploy an application
Log into cPanel as the account and open Software → Node.js Toolkit. Choose Create Application. Provide a name, the Node version, and the source: either a directory in the home directory that already contains a package.json, or a Git repository URL. For a repository, the toolkit clones it into ~/nodejs-apps/<name>/ on each deploy. Set the subdomain the app should answer on; the toolkit creates the subdomain and the proxy rule, and AutoSSL secures it on the next run.
For the example, a minimal Express app in the repository has a package.json with a start script and listens on the port given by the PORT environment variable, which the toolkit injects. Deploy, and watch the build log in the interface. The build runs npm ci or npm install, builds the image and starts the container.
The same from the shell as the account user, useful for CI pipelines:
uapi --user=customer NodejsToolkit create_application name=shop \
node_version=22 source=git repository=https://github.com/example/shop.git \
domain=shop.example.com
uapi --user=customer NodejsToolkit deploy_application name=shop
uapi --user=customer NodejsToolkit list_applications --output=jsonFunction names follow the interface labels on 138; if a call returns “unknown function”, list the module’s functions with uapi --user=customer NodejsToolkit and adjust.
Environment variables and restarts
Open the application’s settings and add environment variables for secrets such as database credentials and API keys. They are stored outside the repository and injected at container start, so a redeploy keeps them. Do not commit a .env file with production values into the repository.
Restart from the interface or with uapi NodejsToolkit restart_application name=shop. A redeploy pulls the repository again and rebuilds the image; a restart only restarts the container. Set the health check path if the application exposes one, so the toolkit can restart a hung process automatically.
Database access works as it does for any cPanel application: create the database and user in cPanel → Databases, and connect to localhost or the socket from inside the container, which the toolkit maps for you. If a connection fails, check that the database user has the host localhost and that the MariaDB socket path matches what the container sees; the application log will say which.
Verify
Confirm the container is running and the subdomain serves it:
uapi --user=customer NodejsToolkit list_applications | grep -E 'name|status|domain'
curl -sI https://shop.example.com/ | head -3As root, podman ps --all run as the account user with su -s /bin/bash customer -c 'podman ps' lists the container and its port mapping. Load the site in a browser and check the toolkit’s log view for startup messages.
Troubleshooting
When the application does not start, the build log and the runtime log in the toolkit are the first stop. The most common messages are a missing start script in package.json, a listener bound to a hard-coded port rather than process.env.PORT, a native module that failed to compile because the image lacks build tools (pin a Node image variant that includes them or prebuild), and a memory limit hit during npm install on a large dependency tree. For the last, the toolkit’s per-application memory limit can be raised in its settings within the account’s LVE or cgroup limits.
If the subdomain returns a 502, the proxy is up but the container is not answering; check that the app is listening on all interfaces, 0.0.0.0, not only 127.0.0.1 inside the container.
Common pitfall
The mistake we see most is treating the container’s filesystem as persistent. Files written inside the container at runtime, uploads for example, are lost on redeploy. Write them to a bind-mounted directory under the home directory, which the toolkit offers as a persistent volume setting, or to object storage. Related to that, the repository is re-cloned on deploy, so uncommitted edits made through File Manager in the application directory disappear; make changes in the repository and deploy them.
CPanel Node.js Toolkit deploy at a glance
Official documentation: cPanel & WHM documentation, Linux man pages.
Related guides: Using MultiPHP Manager and the bulk PHP-version tool in cPanel 136+ · Choosing a cPanel update tier in 2026: LTS 134, RELEASE 138 or STABLE 110 (EOL December 2026) · What changed in cPanel 138: Meridian, Ask AI, Nova, MCP and domain rename.
Frequently asked questions
Does the cPanel Node.js Toolkit replace the Passenger-based Setup Node.js App?
Not yet; both exist on 138. Passenger apps keep running under Apache, while the toolkit runs each app in its own Podman container with its own Node version, so new deployments should use the toolkit and existing Passenger apps can be moved over time.
How long does the first deployment with the Node.js Toolkit take?
The first visit sets up rootless Podman for the account in about a minute, and the initial build pulls the Node image and runs npm install, so allow several minutes; later redeploys reuse cached image layers and are much faster.
Can I keep uploaded files across redeploys of a toolkit app?
Yes, if they are written to the persistent volume the toolkit offers, which is a bind-mounted directory under the home directory; anything written elsewhere inside the container is lost when the image is rebuilt.