---
title: Node.js Runtime
description: Learn what the runtime harness does around a deployed Node.js backend, and write your server to work with its request checks, proxy, and deadlines.
slug: /backend-packages/nodejs-runtime
order: 1
visibility: public
redirects_from: [/backend-packages/node-js-runtime, /backend-packages/hosting]
---

# Node.js Runtime

Node.js Runtime is the platform's startup code, called the runtime harness, which the platform loads before your deployed Node.js application's server starts. It checks incoming requests, routes outbound connections through the platform's proxy, records outbound connections, and enforces request deadlines. The platform injects the settings that turn these protections on at every deploy and promote, so the harness behaves the same in every environment your application has. [Deploy from your computer](/cloud/getting-started/deploy-an-application/) describes each step of a deploy.

## Use it when

Every application deployed through the platform's image build uses Node.js Runtime automatically. There is no handler function to export: supply an ordinary Node.js HTTP server that listens on `PORT`.

The platform starts it with `npm start`, using `scripts.start` in the root `package.json` or npm's default, a root `server.js`. [The hello-world template](/cloud/concepts/turnzero-command/#the-hello-world-template) shows a complete server.

In a deployed copy, the platform sets [`PORT` to `8080`](/cloud/concepts/the-settings-a-deployed-copy-receives/#settings-and-environment-variables-a-deployed-copy-receives). The manifest cannot change it. Your application runs on Node.js 24, whatever the `engines` field in its `package.json` says ([What the application runs under](/cloud/concepts/the-settings-a-deployed-copy-receives/#what-the-application-runs-under)). You install nothing for the runtime harness, and a tzTeam project writes no instance file for it. Read this page when you choose an HTTP client, handle request cancellation, or diagnose refused and interrupted requests.

The manifest's `egress` list defines the outbound destinations, and the platform's proxy applies its own checks on authentication, destination, and port. [Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/) describes both. Node.js Runtime points supported clients at that proxy. It does not replace the proxy's checks or the hosting network's rules.

## What it provides

- **Incoming-request checks** on the Node.js HTTP server. A request from another machine without the [router mark](/cloud/concepts/glossary/#router-mark), a secret header the [serving router](/cloud/concepts/glossary/#serving-router) adds, receives 403 `router_mark_required` before your application's listener runs. A loopback request is accepted without a mark. The checks also cover HTTP upgrade and `CONNECT` requests. A separate HTTPS or HTTP/2 server is not covered. The harness removes the mark header from every request it accepts, so your application's request listener never sees it. It also removes the mark setting from your application's environment and keeps the marks in a file only the container's own user can read.
- **Idle HTTP connections.** On a deployed copy, the harness sets an HTTP server's idle keep-alive to 290 seconds and its headers timeout to 295 seconds, if its keep-alive is still Node.js's five-second default. This prevents the service forwarding requests to your server from reusing a connection your server has closed. An application-set keep-alive and the request timeout are left unchanged. Separate HTTPS and HTTP/2 servers, and local runs, are not covered.
- **A check on scheduled-handler paths.** A request to a schedule's path without the router's schedule-invocation header receives 404 `scheduled_handler_only`. The mark check runs first. The checks use the schedule paths declared at the container's last deploy or promote. A declaration added later reaches the container at the environment's next deploy or promote, and the platform fires a declaration only against a container applied at or after it.
- **Proxy settings**: the environment variables `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`, and an undici global dispatcher. Global `fetch`, undici-based clients, and clients that read those variables use the proxy. Platform endpoints and loopback names bypass it.
- **Records of outbound connections** under the [log source](/cloud/concepts/glossary/#log-source-and-store-source) `harness`: one `egress_establishments` record per host, port, and outcome per minute, with the count and the first and last instants. Each connection whose outcome is not `connected` also gets its own `egress_establishment` record. The harness sends the records through the logging client under your application's own credential, so they outlive the process.
- **An abort signal** at `request.signal`. Requests and [scheduled runs](/cloud/concepts/glossary/#scheduled-run-and-due-instant) can have different deadlines. If the response has not ended within the [grace interval](/cloud/concepts/glossary/#execution-window-and-grace-interval) after the signal, the harness ends the process. A watchdog also ends a process whose event loop is blocked.
- **A pod's last console lines.** Where your application runs as a [pod](/cloud/concepts/glossary/#container-app-and-pod), the harness keeps the first 50 and the last 250 console lines of each process your `start` script runs. Each is cut at 2,048 bytes. When `SIGTERM` reaches the process, the harness ships them to your application's log stream before your own `SIGTERM` handlers run. Sending these lines takes about 50 ms and never more than three seconds. [How long console lines last](/cloud/concepts/how-log-records-arrive/#how-long-console-lines-last) says how long they are kept.
- **The stop signal with the harness.** The harness keeps its `SIGTERM` listener while sending those console lines, so a second signal does not end the process part-way. It then removes its listener. Where you registered no `SIGTERM` handler, the harness raises `SIGTERM` again, so the process ends as it would without the harness. If sending the lines fails or takes too long, the harness writes one `pod_console_keep_failed` line to the console.
- **`harness_refusal`, `window_ended`, and `process_ended` log records**, written to the process's standard output and read with the `container` source. When a process ends, the serving router responds to each other request in flight with 502 `upstream_ended` if no response header had gone out.

Monitoring or tracing code that loads before the harness can read the mark. That is code loaded with `--require`, or with an `--import` your start command puts ahead of the harness's in `NODE_OPTIONS`, and code that wraps the server to watch upgrade requests. Set such code to capture no `x-turnzero-cloud-` header. A server in a worker thread is not covered when the thread runs code passed as a string, or when its environment lacks `NODE_OPTIONS`.

Two records under the `container` source report problems storing or reading the router marks. `router_mark_setting_kept` means the harness could not write the marks' file, so the mark setting stayed in the environment. `router_mark_file_unread` means a process could not read the marks' file, so that process runs with no router-mark check; report the record with its `file` and `code`, as [Feedback](/cloud/guides/feedback/) describes. Your application's code never reads the marks' file or the mark setting.

The connection records leave out connections opened by native add-ons and child processes, and connections to platform endpoints and the logging service's own origin. The records of the minute still open when the process ends go to the process's console, not the log stream.

A stack trace from your handler carries frames in `file:///harness/harness.mjs` after your own, because the harness hands each request to your listener. `read_logs` leaves those frames out, so a trace it answers shows your own frames and Node's.

## Availability

Version 0.12.0 is the package's current version, and this page describes it. Until the library's next publish, `read_library` can return an earlier version of its documents. The library publishes only the package's documents. The platform loads the harness ahead of your code, so no application copies or installs it.

A local run loads no harness, so these protections exist only in a [deployed copy](/cloud/concepts/glossary/#running-copy). A local run's keyed external calls go through the public gateway at `TURNZERO_CLOUD_GATEWAY_URL`, so the machine stores no provider key. [Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/) states what else a local run uses.

The platform injects every setting the harness reads, so your application sets none of them. If a setting is missing or invalid, the protection it controls is off: no router-mark check, no deadline, or no proxy routing.

## Related feature packages

[Database](/cloud/backend-packages/database/) and [Storage](/cloud/backend-packages/storage/) use platform endpoints outside the proxy. [Secrets](/cloud/backend-packages/secrets/) provides named credentials for your application's calls. [Egress](/cloud/backend-packages/egress/) calls external APIs on a stored key through the gateway.

## What an application must do

Declare the outbound HTTPS destinations your application calls in the manifest's `egress` list. [Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/) states the hostname rules and the port. Platform endpoints need no entry.

Read your application's mode as `egress_mode` in the `read_status` response. In `observe` mode, where a new application starts, the proxy records undeclared destinations and permits them. In `enforce` mode it refuses them with 403 `egress_undeclared` ([Observe before enforce](/cloud/concepts/egress-firewall-and-request-limits/#observe-before-enforce)).

Recognize a proxy refusal in your code. Through the harness's dispatcher, global `fetch` rejects with `TypeError: fetch failed`, and its `cause` is an `EgressRefusedError`. An undici client called on the dispatcher directly receives the `EgressRefusedError` itself. Every proxy refusal takes this form, among them a wrong credential (407 `proxy_authentication_required`), a refused port, and a refused address class. Read the error's members:

| Member | What it contains |
| --- | --- |
| `error.cause.code === 'EGRESS_REFUSED'` | True for a proxy refusal. |
| `cause.refusal` | The refusal's name. |
| `cause.status` | The proxy's status. |
| `cause.host`, `cause.port` | The target. |
| `cause.remedy` | For `egress_undeclared`, the manifest edit for a hostname or a fixed sentence for an address literal. Null for every other refusal. |

Use a covered HTTP client. Global `fetch`, undici, and SDKs built on them use the harness's dispatcher, and axios uses the proxy variables. Clients such as `node:https`, node-fetch, got, and ws need an explicit proxy agent from `https-proxy-agent`, passed as the client's `agent` option, or under `agent.https` for got. Without an agent, a call may fail with a connection error or reach the destination directly, depending on the network rules, rather than meet a named proxy refusal.

Build the agent only where `HTTPS_PROXY` is set, as in `const agent = process.env.HTTPS_PROXY ? new HttpsProxyAgent(process.env.HTTPS_PROXY) : undefined`: the harness sets none in a local run, and the constructor throws without it. The variable's URL contains your application's platform credential, so never log or print it. The agent ignores `NO_PROXY`, so give it only to calls to external hosts: a platform endpoint called through it is refused.

Build every absolute address you hand out, such as a link, a redirect, or a file's URL, from `APP_PUBLIC_HOST`, the public hostname the platform injects, or from the router's `x-forwarded-proto` and `x-forwarded-host` headers. A relative redirect, such as `/guestbook`, needs neither ([Serve a web client, step 7](/cloud/guides/serve-a-web-client/#7-serve-a-page-from-your-own-routes-and-take-a-form-post)). The `Host` header names the platform's internal address for the environment, so an address built from it does not resolve outside the platform. Put `https://` before the value of `APP_PUBLIC_HOST`, which has no scheme. [What the router sets on each request](#what-the-router-sets-on-each-request) lists the headers the router sets.

### Handle request cancellation

Handle `request.signal`, and end the response when it fires. Do no application work outside a handler: the harness does not detect a detached promise, timer, or child process that runs on after the response. A handler that does not end after cancellation can make the harness end the process, which interrupts other requests. Upgraded WebSocket connections are outside the request deadline, although the upgrade request passes through the incoming checks. [Use WebSockets](/cloud/guides/use-websockets/) covers the declaration and the limits.

A plain `node:http` server needs no framework for this. On the platform, the harness puts the signal at `request.signal` on every request the server receives. It fires when the request's [execution window](/cloud/concepts/glossary/#execution-window-and-grace-interval) ends, not when the client leaves.

In your local run, use a signal that fires when the response closes unfinished, rather than Node's `request.signal`, which some Node 24 releases abort at a normal request end. The [database-service example](/cloud/examples/database-service/) shows `abortSignalOf` for this.

### Stop cleanly

Handle `SIGTERM` to stop cleanly. When the platform stops a [running copy](/cloud/concepts/glossary/#running-copy), `SIGTERM` reaches your server's process, so a handler there can close the listener, finish the requests in flight, and exit. Without a handler, Node.js ends the process at once. The platform waits 60 seconds on the `pod` [grain](/cloud/concepts/glossary/#grain-and-development-group) and 30 seconds on the `container` grain, then kills what still runs.

On the `pod` grain, the platform's startup code (the runtime harness) sends the process's last console lines first, usually in about 50 ms. A process with no `SIGTERM` handler ends after those lines are sent. The harness handles the signal through Node.js's event loop, so a process with a busy main thread ends only when its event loop runs again.

The image starts `tini -g`, which passes `SIGTERM` to the process group running `npm start`, including Node.js processes in a pipe such as `node server.mjs | tee app.log`. The start shell waits for the script's commands rather than ending at the signal. A pipe's reader, such as `tee`, ends when its input ends. The platform collects standard output under the `container` source; [Read logs and counters](/cloud/guides/read-logs-and-counters/) says how to read it.

On each version row from `list_versions`, `harness_current` compares only the runtime harness bundle, not the image's startup command. An older image that starts `npm` directly instead of `tini` can still report `true`. Deploy a new version to update that startup command. Restarting or promoting the older version keeps its original image.

Keep the server as your `start` script's last command, alone or after `&&`, such as `node server.mjs` or `node migrate.mjs && node server.mjs`. A command after `;`, or after `&&` when the preceding command exits 0, starts even after the stop signal. The signal does not reach a process started after it; that process may run until the grace period ends.

Commands in your `start` script run under `/bin/sh` (dash), with `SIGTERM` ignored by the shell. A long-running non-Node command that inherits this ignored signal runs until the grace period ends. Use plain sh syntax, or move bash-only syntax such as `[[ ]]`, `source`, or arrays into a script file whose first line is `#!/bin/bash`.

Deploy the application again to use this process and shell setup. Restarting an older image keeps its existing setup.

### Keep data and read records

Keep no file the application needs again on the running copy's own disk: put files in [Storage](/cloud/backend-packages/storage/) and records in [Database](/cloud/backend-packages/database/) ([The local file system does not persist across restarts or redeploys](#the-local-file-system-does-not-persist-across-restarts-or-redeploys)).

Keep the platform credential secret. The platform injects it as `TURNZERO_CLOUD_APP_TOKEN`, one credential per environment, bound to the environment it was minted for. The proxy's authentication and the harness's own log writes use it. Do not put it in source code or print it in logs.

Read the harness's records with `read_logs` and the `harness`, `egress`, `router`, and `container` sources. [Read logs and counters](/cloud/guides/read-logs-and-counters/) states what each source contains, which environment `read_logs` reads, and how to filter the records by declared and undeclared destinations.

A request past the router's deadline receives 504 `window_ended`, or its streaming response is cut. Where the process then ends, an intermediary can retry an idempotent request on the restarted process, and that caller then receives the new response. A client address past the router's per-address limit receives 429 `rate_capped`, and its request never reaches the process. [Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/) states the deadline and the bound.

## The local file system does not persist across restarts or redeploys

[What a deployed application needs](/cloud/concepts/what-a-deployed-application-needs/#where-data-lasts-the-local-file-system-does-not-persist) gives the fuller account of where data lasts. A deployed application runs in a container or a pod, and what its code writes to the local disk does not persist. Keep no file the application needs again on the [running copy](/cloud/concepts/glossary/#running-copy)'s own disk. A deploy, a promote, a rollback, `restart_application`, and the platform's own replacement each start a new copy with only what its deploy built, and so does the start after an idle stop. Whatever the code wrote to the disk, `/tmp` included, is then lost. Put files in [Storage](/cloud/backend-packages/storage/) and records in [Database](/cloud/backend-packages/database/).

## What the router sets on each request

The serving router sets four headers on every request it forwards to your application:

| Header | What it contains |
| --- | --- |
| `x-forwarded-host` | The hostname the request arrived on. |
| `x-forwarded-proto` | Always `https`, because the encrypted connection ends before the router. |
| `x-forwarded-for` | The client's address as the router knows it. Read the first entry, since a hop after the router may append its own. |
| `x-request-id` | The router creates one sixteen-character hexadecimal identifier for each request and includes it on every response to that request. A refusal made before the router accepts the request, because of its body or HTTP message format, is the exception. |

The router sets the four after the client's headers, so a client's copy never arrives. The `Host` header names the platform's internal address for the environment, never the public hostname. Build an absolute address from `x-forwarded-proto` and `x-forwarded-host`, or from `APP_PUBLIC_HOST`. The router sets no other forwarding header, such as `Forwarded` or `x-forwarded-port`, so trust none. The router also sets the headers of a [scheduled run](/cloud/backend-packages/schedule/#what-it-provides) and of [a signed-in end user](/cloud/concepts/verifying-an-end-user/), which those pages describe.

The router passes an application's redirect status and `Location` header to the caller without following the redirect.

A local run has no router and no `APP_PUBLIC_HOST`. Fall back to the request's `Host` header and `http`. A test that requests a local server expects `http` addresses, or sends `x-forwarded-proto` itself.
