Run your app on your computer #
On this page
Prompt:
Run this on my machine so I can try it before I deploy.
Also works:
- "Start the server here."
- "I want to test it locally first."
To use platform development data and services, write .env with turnzero provision --application <application id>. Then start the app with turnzero run --port 3000. This provisioned run uses development data and logs. If the app has no development environment, sign-in still uses production's realm; see what a local run reaches.
To run against your own PostgreSQL before the first deploy, see Run against your own PostgreSQL.
What your AI tool does #
For a provisioned run using platform development data and services, your AI tool:
- Reads the
skill:deployskill (read_context, idskill:deploy) and follows its rules for a run on your own machine. Those rules write.envthrough theprovisioncommand. - Gives each setting your manifest binds to a stored secret its own local value, on a line of
.env, and copies each plain setting's value from the manifest onto a line of.env. - Checks that port 3000 is free, then starts the application in the background with the
runcommand,turnzero run --port 3000. - Requests the health path your manifest names until it returns 200, while the
runcommand is still running. - Tells you the address the application answers on. When you are done, it stops the process it started and every process under it.
- Never commits
.env. - Asks you for one thing only: a local value for a setting your manifest binds to a stored secret, such as a provider's test key, where the project holds none.
What you need #
- Node.js 24 or later, and npm, installed on your computer. See What your computer needs.
Before your AI starts #
For the AI tool: Before a provisioned run using platform development data and services, do the following.
- Connect and sign in (Connect your AI assistant).
- Create the application and write its manifest, as steps 1 and 2 of Deploy from your computer describe.
- List
.envin your ignore file, becauseturnzero provisionwrites credentials into it.
Steps #
1. Write the environment file #
A local run uses the application's development data, so your test data never lands in production's database, files, or logs. Two things are still shared with production. On an application with one environment, sign-in uses production's realm, so a tester who signs up becomes a live end user. And a key for an external API that is stored at account scope, for every environment, is the same key production uses. Step 4 says what a local run reaches.
With a shell that can reach the platform, your AI tool can complete this provisioned run using its MCP sign-in alone; no computer sign-in or minted token is needed. In the application's folder, your AI tool runs turnzero provision --application <application id> with nothing piped. Where this computer holds no token, the command keeps a verifier here and prints a challenge and the submit_manifest call to make: the application, its manifest, local_run: true, and code_challenge. Where CI is set, it sends nothing instead and ends with status 3, as turnzero deploy does.
Your AI tool makes that call. It first runs the response's provisioning.command_npx, or provisioning.command_npx_windows on Windows, once, as given. Run it in the same folder before provisioning.expires_at, fifteen minutes after the call. The installed forms are provisioning.command and provisioning.command_windows. Under a token, the first provision command does the work itself.
The verifier is a secret the command keeps on this computer, and the challenge it prints matches it. So only this computer can use the secret grant, the short-lived permission, that the call returns. To re-mint a credential is to replace it with a new value.
The returned command uses turnzero provision --application <application id> --claim. It presents a verifier stored on this computer to claim the grant, so copying the command to another computer cannot replace the credentials.
The provision command replaces the local run's platform credential, and its database credential if the manifest declares a database, each once. It writes .env, or the file --settings-file names, .env or a .env.* name. These credentials belong to the local run, never production, and the next provision command replaces them.
--settings-file requires turnzero 0.35.0 or later.
A run on your machine before a deploy starts your real server against development, which catches what the test doubles cannot, so it uses the development credentials.
To keep the credentials out of the project's folder, give turnzero provision a file outside it, such as --settings-file ../.env.turnzero. The file's name must still be .env or start with .env.. Where the file's folder holds neither package.json nor manifest.json, the command prints a warning, but it still writes the file. The warning gives two fixes: move the file into the application's folder, or name it when you start the run. For the second, start the application with turnzero run --settings-file ../.env.turnzero, or with node --env-file=../.env.turnzero src/main.mjs, your own entry file in place of src/main.mjs.
Running the returned provision command again after it replaced a credential normally finds that its grant has already been used. It prints the challenge and the submit_manifest call again; that call returns a new grant. Running on your machine describes it.
Where development runs a version, turnzero provision restarts it after creating the last replacement credential. If a development deploy is still running, the response gives tzcloud_restart_application on development; your AI tool calls it once the deploy ends.
2. Read the settings the file holds #
The application reads these settings from the file at start. The provision command writes eight where a development database stands, or the five non-database settings otherwise:
APP_DATABASE_URL, the development database's connection string, built from its connection details and the new password, withsslmode=verify-full;APP_DATABASE_DIRECT_URL, withturnzero0.50.0 or later: the development database's connection string on its direct port, 5432;APP_DATABASE_CONNECTION_LIMIT, ten client connections per process, the pool's maximum, as a deploy sets it;TURNZERO_CLOUD_APP_TOKEN, the development platform credential, which your application presents when it calls the platform;APP_ENVIRONMENT=local, which names the log stream a local run writes to;TURNZERO_CLOUD_API=https://turnzero.ai, the platform address the application uses for sign-in and account reads;TURNZERO_CLOUD_GATEWAY_URL=https://turnzero.ai, the address for storage, logging, and external-API calls, the same as the line above, since the platform serves both;TURNZERO_CLOUD_APPLICATION, the application's identifier, as a deploy sets it.
For a local run, turnzero provision writes APP_DATABASE_URL on the transaction-mode pooler's port, 6432, and APP_DATABASE_DIRECT_URL on the direct port, 5432. Code that holds a session across transactions must read APP_DATABASE_DIRECT_URL locally and when deployed (Session work).
If an older turnzero command wrote .env, repeat step 1 with the current command before running a migration example that reads APP_DATABASE_DIRECT_URL.
Where no development database stands, turnzero provision writes none of APP_DATABASE_URL, APP_DATABASE_DIRECT_URL and APP_DATABASE_CONNECTION_LIMIT, and writes the other five. It keeps any existing lines under those three names. An application that reads none of these settings runs on your machine without turnzero provision. A hosted deploy never needs it.
A setting your manifest binds to a stored secret gets no line from turnzero provision, because no call returns a stored value. Put its local value on a line of your own in .env, which turnzero provision keeps when it runs again. A deploy's zip leaves out .env and every .env.* file, and your ignore file keeps .env out of Git. So the value reaches neither the artifact nor a committed file, which Store a secret rules out.
A plain setting of your manifest, one given as {"value": "<text>"}, gets no line from turnzero provision either. Copy its value from the manifest onto a line of your own in .env, such as SITE_TITLE=Receipts, and change that line when you change the manifest (Set a value that is not secret).
3. Start the application #
Start the application with the run command, in the folder that holds its package.json. run starts npm start, as the platform does. The application receives your shell's settings with every setting of .env laid over them, so where both name a setting, the file's value wins. A value left in your shell from another project never replaces the file's. A test checks this run command against the one the platform composes.
turnzero run --port 3000
In Windows PowerShell, use turnzero.cmd instead of turnzero. --port chooses the port you open. Without sign-in or a client/ listener, it sets the application's PORT directly, overriding .env and the shell. turnzero provision does not write PORT into .env; a deployed copy receives it from its image.
The run command runs until the application ends, so your AI tool starts it as a background process and reads its lines. Before the application's own lines, it lists the settings .env sets and gives the address, such as http://localhost:3000/.
With turnzero 0.35.0 or later, where the application's folder holds client/, the command serves its files at that address, ahead of your application's routes. It gives the application a free port as PORT; your server must listen on that setting. The printed lines name both ports. Open the command's address.
Without --sign-in, that listener binds on all network interfaces. An application that normally binds only to loopback can therefore be reached through this listener from elsewhere. With --sign-in, the listener binds only to loopback.
A run without a numeric port serves no client file. Serve a web client covers older command versions and starting the server directly.
The run command passes the application's output through. Where the application prints the value of TURNZERO_CLOUD_APP_TOKEN, APP_DATABASE_URL or APP_DATABASE_DIRECT_URL exactly as it received it, or the database password, the run command hides it.
With the provisioned values, a printed APP_DATABASE_DIRECT_URL becomes <APP_DATABASE_DIRECT_URL>. Other hidden values show the setting's name between angle brackets. A value printed in another form, encoded or split for example, is not hidden, and neither is a value under eight characters. So have the application print none of them.
Before it starts turnzero run, your AI tool checks that port 3000 is free: the connection for a request to http://127.0.0.1:3000/health must be refused. Otherwise a copy left from an earlier run could answer the health check, though your code never started. For the same reason, a 200 counts only while the run command is still running. Where turnzero run has ended, for example because the port was already in use, another process answered.
A server with a database may wait for its migrations before listening. Until it listens, the command's listener responds with 502; a direct connection to the application's port may be refused. Retry the health path until it returns 200. With curl -fsS --retry 30 --retry-delay 1 --retry-connrefused http://127.0.0.1:3000/health, curl tries again each second, up to thirty times.
To stop the application, interrupt turnzero run, as Ctrl+C does in a terminal. On Windows, ending only the run command's own process leaves the application running. So your AI tool ends the process it started and every process under it, its process tree, by that process's id. In PowerShell, taskkill /T /F /PID <pid> ends turnzero run, npm start, and the application together.
Your AI tool never ends a process found by its port, which may belong to something else. The run command prints its process id and the stop command for your system, just after its version line.
Check the run in one command #
Some tools' shells end a background process as soon as the command that started it returns. Such a tool checks the run in one command instead. That one command starts the entry file your start script runs, requests the health path, and stops the server. It starts Node.js directly, with --env-file, because every shell can stop a process it started itself. On Windows, a plain stop of the run command leaves the application running. The tool makes the same port check first. Change src/main.mjs to your own entry file. In bash:
PORT=3000 node --env-file=.env src/main.mjs & server=$!
curl -fsS --retry 30 --retry-delay 1 --retry-connrefused http://127.0.0.1:3000/health
kill $server
In Windows PowerShell:
$env:PORT = '3000'
$server = Start-Process node -ArgumentList '--env-file=.env', 'src/main.mjs' -NoNewWindow -PassThru
curl.exe -fsS --retry 30 --retry-delay 1 --retry-connrefused http://127.0.0.1:3000/health
Stop-Process -Id $server.Id
Windows PowerShell 5.1's Start-Process takes no -Environment parameter. Set each variable with $env: before the call, as above, and the started process inherits it.
Each try whose connection is refused prints a line such as Failed to connect before the answer. A pause of a second before one request is not enough. A server whose migrations run first can take longer, and so can a PowerShell job, which starts a new PowerShell process.
A variable already set in your shell wins: node --env-file keeps it and ignores the file's line. A TURNZERO_CLOUD_APP_TOKEN left in the shell from another project would reach the platform in place of the file's credential. Before the check, unset in your shell each setting the file supplies, or open a new shell.
Where your AI tool's command policy refuses Start-Process, the script in Your AI tool refuses a background process or a file deletion makes the same check as one node --env-file=.env check_local.mjs command. It starts your entry as a child process, requests its health path, and stops it.
4. Know what a local run reaches #
On your machine, the application uses development's data and services:
- A file your application stores goes to the development partition of its storage area.
- A log line goes to the
locallog stream, whichread_logsreads withenvironment: "local". - A call to a declared upstream, an external API your application declares, goes through the platform's public gateway. The gateway adds the development key value, so your machine holds no provider key.
- The database is the development database. The run reaches it over the database server's public address, which the platform's developer network rule opens to any address.
The application has one development database, and the APP_DATABASE_URL that turnzero provision writes reaches it. So a local run's migrations and writes change that shared database. Every other local run of the application, and the deployed development environment where development is on, use the same tables. To test the data layer without touching it, use the test double that Test your application locally describes.
To start from empty development data, your AI tool calls clear_development_database, which needs your approval in the browser, as Add a database describes.
On your machine, your backend checks a signed-in user's session through the platform's verification route, under the development platform credential. It must ask, because .env holds no realm keys. Tell which user sent a request shows how.
With turnzero 0.38.0 or later, start turnzero run --port 3000 --sign-in <hostname> to sign in from http://localhost:3000/. Name the application's development hostname where development is on, otherwise its production hostname or a served custom domain. The command checks the hostname before starting.
Use an emailed code. If a passkey offer follows, choose Not now. Federated sign-in and passkeys complete on the hosted hostname, so they cannot complete this local sign-in. Browser sign-in on localhost has not been checked in Chromium-family browsers, Firefox, or Safari.
The session is shared with every server you open at localhost, on any port. Use this route only while you trust the other local projects running on this computer.
On an application with one environment, sign-in uses production's realm, so testers become end users of the live application. With development on, they use development's realm. Without --sign-in, hand a hosted session to the run as Test a local run shows.
A local run loads no runtime harness, so it lacks the protections Node.js Runtime says only a deployed copy receives.
The platform sends no scheduled run to a local run. To test a scheduled job, your AI tool sends the request itself, with the platform's four headers, as Send a run to your machine shows.
With client/ and a numeric port, turnzero 0.35.0 or later answers a GET for each client file before your routes. A route at the same path receives no GET. It reads each file on request, so an edit appears on the next load.
A file name the deploy's zip leaves out, a path containing a link, or a name in another letter case falls through to your application. .deployignore is not read locally. Serve a web client describes the limits and the manual alternative.
Expected result #
For a provisioned run, the application starts on your machine and its health path returns status 200. Its log lines reach the local stream, and the project contains .env, which is not committed.
Run against your own PostgreSQL #
You can run your application against a database on your own machine before its first deploy. This route needs no Turn Zero Cloud sign-in, turnzero command or library entry.
Use this route only if your application reads none of these settings:
TURNZERO_CLOUD_APP_TOKENTURNZERO_CLOUD_APITURNZERO_CLOUD_GATEWAY_URL
If it reads any of them, use the provisioned run in steps 1–4. Use those steps whenever the application needs platform services or shared development data.
This run is separate from the platform's local run and reaches none of its development records. The platform's Transport Layer Security (TLS), database isolation, backups and metering do not cover your own server.
Start a database #
Choose one of these three ways. Check that port 5432 is free before starting a new server.
PGlite with its socket server runs PostgreSQL in Node.js and accepts PostgreSQL client connections. Start it with these package versions and keep the process running while you use the application:
npx -y -p @electric-sql/pglite@0.5.8 -p @electric-sql/pglite-socket@0.2.11 pglite-server --db=./dev-db --port=5432
It keeps the database in ./dev-db. In Windows PowerShell, use npx.cmd in place of npx.
With Docker installed and running, start the official PostgreSQL image:
docker run --rm -d --name dev-postgres -e POSTGRES_PASSWORD=postgres -p 127.0.0.1:5432:5432 postgres:16
This example uses postgres for the database name, user and password, and publishes port 5432 on this computer only. Stopping the container removes its database.
With PostgreSQL installed and a data folder already initialized, start that server with pg_ctl. On Linux and macOS, give it a socket folder your user can write, such as /tmp:
pg_ctl -D <data folder> -o "-k /tmp" -l postgres.log start
Replace <data folder> with its path, quoted if it contains spaces. The -o "-k /tmp" option avoids a startup failure when the default socket folder, such as /var/run/postgresql, is not writable by your user. On Windows, omit -o "-k /tmp"; PostgreSQL creates no Unix socket by default.
Use this server's own user, password, port and database in the connection string below. It connects over TCP to 127.0.0.1, so the socket folder does not change that host.
Set the database connection #
For the PGlite or Docker example, put these lines in .env in the application's folder:
APP_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres
APP_DATABASE_DIRECT_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres
APP_DATABASE_CONNECTION_LIMIT=1
Your server has one address, so both settings use the same value; the guides' migration calls read APP_DATABASE_DIRECT_URL.
For an installed server, change the connection details in both lines to match it. Keep the connection limit at 1 for PGlite. This example uses no TLS, so do not copy sslmode=verify-full from the platform's development connection string.
If the application reads APP_ENVIRONMENT, also add APP_ENVIRONMENT=local to .env. Keep .env out of Git.
Start the application #
Start the CommonJS and Express sample with:
node --env-file=.env src/server.cjs
For another application, replace src/server.cjs with its entry file. A value already set in your shell takes precedence over .env; clear conflicting database settings or open a fresh shell first.
The sample creates its initial table before listening. Its /health route returns 200 when it can query your database, and /notes returns an empty list on a fresh database.
Refusals #
See the refusals reference for other platform errors.
Before any request, turnzero provision checks for an older Database package in the environment file's folder. A refusal ends with status 3 and leaves credentials and the environment file unchanged. Follow the printed remedy, then run the provision command again.
The provision command's grant refusals come from its secret grant. Where its first re-mint is refused, the command writes nothing and prints the challenge and the call again. The provision command is refused gives the check for each.
turnzero run without --sign-in makes no platform call. With --sign-in, it reads the credential turnzero deploy uses, checks the platform, and calls read_status before starting. A missing credential, an unrecognized hostname, or a failed bind ends the run with status 3 before the application starts.
run also ends with status 3 before the application starts if the folder holds no package.json or .env has a line it cannot read. Running on your machine lists the forms it reads.
On Windows, if run finds no npm entry file and PATH is set, it checks the application folder and PATH using PATHEXT. If that check finds no npm, it prints this line:
npm start could not be started (ENOENT): npm stands beside Node.js and must be on the PATH. No application was started.
It ends with status 3 before starting a shell or the application. Put the npm installed with Node.js on PATH, then run the command again.
| Refusal | Status | Cause | Remedy |
|---|---|---|---|
secret_grant_spent |
403 | An earlier run of the returned provision command already used its grant, or someone who read this computer's credential file used it first. |
Make the call the command prints again, then run the provision command it returns as given. |
secret_grant_expired |
403 | The provision command ran after its expires_at. |
Make the call the command prints again, then run the provision command it returns as given. |
authentication_required |
401 | The provision command was changed, for example to give another --application, or it ran on a computer other than the one that printed the challenge, so its verifier claims no grant. |
Make the call the command prints again, then run the provision command it returns as given. |
Related #
- Deploy from your computer deploys the application once it runs on your machine.
- Test your application locally runs the tests over the test doubles, with no call to the platform.
- The turnzero command describes
provisionandrun, and the formsrunreads in the file. - Applications and environments compares the local run, the deployed development copy, and the tests.
- Secrets in Troubleshooting covers a refused
provisioncommand and a shell value that wins over the file. - A deployed app's settings compares the settings a deployed copy reads with those in the local environment file.