A deployed app's settings #

View this page as Markdown

On this page

Turn Zero Cloud supplies runtime settings as environment variables, available through process.env. Local runs use the settings described in Run your app on your computer.

Your server listens on PORT, and builds every absolute link, redirect, and file address it hands out from APP_PUBLIC_HOST, never from the request's Host (Settings and environment variables a deployed copy receives).

Settings and environment variables a deployed copy receives #

Each deploy, promote, platform redeploy, and restart_application supplies these settings to the new running copy.

Setting What it contains When it is present
PORT 8080, the port your server listens on. Always.
APP_PUBLIC_HOST The environment's public hostname, never the request's Host. It carries no scheme and no path, such as my-app-x1y2z3.ai.host, so an address you hand out is https:// followed by it. Build every absolute link, redirect, and file address you hand out from it, because the request's Host header names the platform's internal address for the environment. After a rename, the rename's restart writes the new hostname; where the restart is refused, the copy keeps the old one until the next deploy or promote. On production, once a domain of your own serves, it is that domain until you detach it, and the platform restarts the copy at each change. Where that restart is refused or fails, the copy keeps the old value until production's next deploy, promote, or restart_application (Attach your own domain). Always.
APP_ENVIRONMENT development or production. Always.
APP_VERSION The version applied, the integer read_status and list_versions show. A health path that returns it shows which version responds. Always.
APP_DATABASE_URL Secret database connection string: pooled on deploy; a version keeps its recorded address on promote, rollback, restart or platform redeploy. Where the environment has a database.
APP_DATABASE_DIRECT_URL Secret database connection string on the direct port, for work needing one server session. Where the environment has a database.
APP_DATABASE_CONNECTION_LIMIT 10 database connections per process: set the client pool's maximum to this value. The role accepts twice that number. Where the environment has a database.
TURNZERO_CLOUD_API The platform's origin, for sign-in, account reads, the verification route, and management calls. Its value is scheme and host with no path or trailing slash, such as https://turnzero.ai, and you append your call's path. Calls to it, and to TURNZERO_CLOUD_GATEWAY_URL, need no entry in the manifest's egress (Platform endpoints). Always.
TURNZERO_CLOUD_APPLICATION The application's identifier, the value create_application returned. Always.
TURNZERO_CLOUD_APP_TOKEN The environment's platform credential, the bearer for storage, egress, and logging calls. It is kept secret. Always.
TURNZERO_CLOUD_GATEWAY_URL The origin for storage, egress, and logging calls. Without it, send those calls to TURNZERO_CLOUD_API. Where the platform configures a separate origin.
TURNZERO_CLOUD_REALM_KEYS The end-user realm's public key set, as one JSON string, its keys empty before the realm's first sign-in. Where the environment has a realm.
HTTPS_PROXY, HTTP_PROXY, NO_PROXY The proxy settings, in upper and lower case, for a client that needs an explicit proxy agent. The runtime harness, the platform's code that runs in your process, sets them as the process starts, so read them at run time. Where outbound calls go through the platform's proxy.
HOME /tmp. On an environment that runs as a pod.

Turn Zero Cloud supplies a deployed copy with both TURNZERO_CLOUD_API and TURNZERO_CLOUD_GATEWAY_URL today. Send storage, egress and logging calls to TURNZERO_CLOUD_GATEWAY_URL, and sign-in, account reads, verification and management calls to TURNZERO_CLOUD_API.

The application's audience kind changes none of these settings: a public, invited, or workforce application receives the same list. TURNZERO_CLOUD_REALM_KEYS is set only if the environment has a realm. Declaring the accounts service in the manifest creates that realm. An invited or workforce application that has never declared accounts therefore receives no realm keys.

No setting is named NODE_ENV: neither the image nor the platform sets it, and the manifest cannot bind a name under NODE_. An application whose framework reads it sets the mode it wants in its own code.

The copy receives its own identifier as TURNZERO_CLOUD_APPLICATION, so code that binds a storage area to the application reads it there, not from a copy in the code. No setting contains an issue-tracking space or its token: a backend reaches its application's space through the egress gateway, as the Issue Tracking package says. No setting is named TURNZERO_CLOUD_ORIGIN, which only the turnzero command reads. Your code reads the platform's origin from TURNZERO_CLOUD_API.

Changes to a running copy's settings #

A running copy keeps the values it started with.

After platform staff change the size's connection-limit value, APP_DATABASE_CONNECTION_LIMIT takes it at each environment's next deploy, promote or restart_application. A running copy keeps the value it started with.

If an environment has a database and its size's connection limit is unset, the platform refuses restart_application with plan_quantity_unset. It also refuses restarts caused by a rename or a change of domain, credential or size. A redeploy started by platform maintenance goes ahead instead: it leaves the setting out and writes a warning to the log. The Database package's pool then uses one connection (The connection limit).

The manifest's settings member adds your own settings to the table's, in two forms. A binding names a setting and the stored name whose value it receives, kept secret like the platform credential. A plain setting names a setting and its value, {"value": "<text>"}, which the copy receives as a plain setting, the same in every environment. Your code reads either form from process.env. A value you store with store_secret is a setting only where the manifest binds it.

A platform redeploy re-applies the bound and plain settings the running copy started with. It leaves out a binding if the stored secret has been removed. It also leaves out a setting if an upstream's sdk_settings now supplies the same setting name. For either omission, the platform writes a warning to your log naming the setting, never its value.

Where a bound name exists and the store does not respond, the redeploy ends failed bound_setting_unreadable, and the running copy keeps running. Bind a stored value to a setting shows a binding, and Set a value that is not secret a plain setting.

A declared upstream's sdk_settings add one or two more, under the names you declared. The base-URL setting contains the gateway's address for that upstream. The key setting contains an egress key, kept secret: a credential the platform creates for that upstream and this copy alone. Each deploy, promote, and platform redeploy creates fresh egress keys from the upstream declarations existing then. The upstream's own key never enters the copy. An unchanged SDK shows how an SDK uses them.

The platform sets other settings for the runtime harness, and your code never reads them: HOSTING_WINDOW_REQUEST_SECONDS, HOSTING_WINDOW_SCHEDULE_SECONDS, HOSTING_WINDOW_GRACE_SECONDS, HOSTING_SCHEDULE_PATHS, EGRESS_PROXY, EGRESS_PLATFORM_ENDPOINTS, NODE_OPTIONS, npm_config_update_notifier, and npm_config_script_shell. The router mark's setting, ROUTER_MARK_SECRET, is the platform's too.

The runtime harness removes ROUTER_MARK_SECRET from the environment before your request listener runs (Node.js Runtime). Where the harness cannot save the mark to its own file, the setting stays, and one line in your log names it.

What the application runs under #

The running image is Docker Hub's node:24-bookworm-slim, pinned by digest: Node.js 24 and its npm, and a minimal Debian 12 on Linux x64 with glibc. It contains no compiler, git, Python, or curl.

Its first process is tini -g. The platform sets npm_config_script_shell to /harness/start_shell, which starts /bin/sh (dash) with SIGTERM ignored by the shell. It waits for the script's commands; Node.js Runtime explains how to write a start script that stops cleanly.

On an environment that runs as a pod, the process runs as user ID (uid) 1000. On its own container it runs as root, because the image names no user. Either way the application's files under /app belong to uid 1000. Where each environment runs says which environment runs as a pod: every development environment, and production on Shared 0.5 GB, where shared compute has room.

What the code writes to the disk, /tmp and the HOME folder included, is lost whenever the copy is replaced or stops (Running copy). A file the application needs again goes in a storage area or a database.

It runs JavaScript, code compiled to JavaScript or WebAssembly, and native modules. A native module is compiled on node:24-bookworm at the image build or prebuilt for Linux x64 with glibc, and can use only the slim image's shared libraries. The build loads each one and fails on one that does not load (the load check). A module opening a library only at first use fails at that use.

The copy also runs under the platform's network controls and request limits, which Egress firewall and request limits explains. An environment whose warm floor is 0 stops after a spell with no requests, and the next request waits while a copy starts.