On Runtime, an App is a Linux machine that keeps your app in
/app running on port 8080. It starts the app the way Heroku and Render do:
the Procfile's web: line, else npm start. An App never pauses, so it is
billed for its memory the whole time it runs, at $0.008 per
GB-hour, plus $0.03 per vCPU-hour of CPU it uses
(pricing).
Get the app ready
Every host that runs Node.js apps makes the same few demands. An app that meets them moves between hosts without changes.
| What the host needs | How to give it |
|---|---|
| A port to send traffic to | Listen on process.env.PORT, with a default for your laptop |
| A way to start the app | A start script in package.json. With none, npm runs node server.js |
| The same dependencies every time | Commit package-lock.json, and install with npm ci |
| A known Node.js version | An engines field, such as "node": ">=22" |
| Configuration outside the code | Read keys and URLs from environment variables, never from committed files |
| A clean stop | Handle SIGTERM: stop taking requests, finish the ones in flight, then exit |
A minimal server that meets them:
JavaScriptconst http = require("node:http");const port = Number(process.env.PORT ?? 8080);const server = http.createServer((req, res) => res.end("ok\n"));server.listen(port, () => console.log(`listening on ${port}`));process.on("SIGTERM", () => server.close(() => process.exit(0)));Listen on all interfaces, which is what listen(port) does with no host. A
server bound to 127.0.0.1 answers on your laptop but not behind a host's
router.
Deploy it on Runtime
This script creates an App, writes package.json and server.js to /app,
restarts the App's server so it runs them, and calls the app through a
preview, an HTTPS address for the port. It uses curl
and jq against the API, with your key in
RUNTIME_API_KEY.
Terminalapi=https://api.withruntime.com/v2auth="Authorization: Bearer $RUNTIME_API_KEY"# An app's machine starts the app in /app the way Heroku does: npm start.app=$(curl -sf -X POST "$api/apps" -H "$auth" -H "Content-Type: application/json" -d '{}' | jq -r .id)trap 'curl -sf -X DELETE "$api/apps/$app" -H "$auth" > /dev/null' EXITprintf '{"scripts":{"start":"node server.js"}}' | curl -sf -X PUT "$api/apps/$app/files?path=/app/package.json" -H "$auth" \ -H "Content-Type: application/octet-stream" --data-binary @- > /dev/nullcat <<'JS' | curl -sf -X PUT "$api/apps/$app/files?path=/app/server.js" -H "$auth" \ -H "Content-Type: application/octet-stream" --data-binary @- > /dev/nullconst http = require("node:http");const port = Number(process.env.PORT ?? 8080);http.createServer((req, res) => res.end(`hello from Node ${process.version}\n`)).listen(port);JS# Restart the app's server so it runs the new code.curl -sf -X POST "$api/apps/$app:exec" -H "$auth" -H "Content-Type: application/json" \ -d '{"cmd": "sudo pkill -f runtime-app || true; sudo -E -u runtime runtime-app", "wait": false}' > /dev/nullpreview=$(curl -sf -X POST "$api/sandboxes/$app/previews" -H "$auth" \ -H "Content-Type: application/json" -d '{"port": 8080}')url=$(jq -r .url <<< "$preview")token=$(jq -r .token <<< "$preview")curl -sf --retry 40 --retry-all-errors --retry-delay 1 "$url" -H "x-runtime-preview-token: $token"# hello from Node v...The trap deletes the App when the script ends. Leave it out to keep the app
running. A private preview needs its token in the x-runtime-preview-token
header. For a real project, upload the whole folder instead of single files,
then run npm ci in /app before the restart.
Mistakes to avoid
- A hard-coded port.
listen(3000)works on your laptop and fails on a host that routes to another port. ReadPORT. - Dependencies from
npm install. It can resolve newer versions than you tested.npm ciinstalls exactly what the lockfile says, and fails if the lockfile andpackage.jsondisagree. - Secrets in the repository. A
.envfile committed once stays in the history. Give the host the values as environment variables or secrets. - Work that dies with the request. A host may restart the process at any time. Keep sessions and uploads in a database, an object store or a volume, not in memory or on the local disk alone.
Related
- What is a platform as a service (PaaS)?
- How to deploy an HTTP function, for a handler that pauses between requests
- How to deploy a Docker container, when the app already ships as an image
- How to add a custom domain
Sources
- npm Docs, scripts, checked 17 November 2026
- Node.js, HTTP, checked 17 November 2026
- Heroku Dev Center, The Procfile, checked 17 November 2026
Facts on this page were checked on 17 November 2026.