---
title: "Run your app on your computer"
description: Run your app with settings from turnzero provision, or connect it to your own PostgreSQL before its first deploy.
slug: /guides/run-your-application-on-your-machine
order: 22
visibility: public
redirects_from: [/guides/run-your-app-on-your-computer]
---

# Run your app on your computer

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](/cloud/concepts/glossary/#realm); see [what a local run reaches](#4-know-what-a-local-run-reaches).

To run against your own PostgreSQL before the first deploy, see [Run against your own PostgreSQL](#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:deploy` [skill](/cloud/concepts/glossary/#skill) (`read_context`, id `skill:deploy`) and follows its rules for a run on your own machine. Those rules write `.env` through the `provision` command.
- 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 `run` command, `turnzero run --port 3000`.
- Requests the health path your manifest names until it returns 200, while the `run` command 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](/cloud/getting-started/prerequisites/).

## 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](/cloud/getting-started/connect-your-tool/)).
- Create the application and write its manifest, as steps 1 and 2 of [Deploy from your computer](/cloud/getting-started/deploy-an-application/#1-create-the-application) describe.
- List `.env` in your ignore file, because `turnzero provision` writes 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](#4-know-what-a-local-run-reaches) 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](/cloud/concepts/glossary/#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](/cloud/concepts/turnzero-command/#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, with `sslmode=verify-full`;
- `APP_DATABASE_DIRECT_URL`, with `turnzero` 0.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](/cloud/concepts/glossary/#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](/cloud/guides/add-a-database/#work-that-needs-one-server-session)).

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](/cloud/concepts/glossary/#artifact) nor a committed file, which [Store a secret](/cloud/getting-started/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](/cloud/guides/author-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.

```text
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](/cloud/guides/serve-a-web-client/#6-serve-the-files-yourself-in-a-local-run) 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:

```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:

```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](/cloud/troubleshooting/setup/#your-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 `local` log stream, which `read_logs` reads with `environment: "local"`.
- A call to a [declared upstream](/cloud/concepts/glossary/#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](/cloud/concepts/glossary/#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](/cloud/guides/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](/cloud/guides/add-a-database/) describes.

On your machine, your backend checks a signed-in user's session through the platform's [verification route](/cloud/concepts/glossary/#verification-route), under the development platform credential. It must ask, because `.env` holds no realm keys. [Tell which user sent a request](/cloud/guides/add-sign-in-to-your-app/#3-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](/cloud/guides/test-sign-in-with-test-end-users/#7-test-a-local-run) shows.

A local run loads no [runtime harness](/cloud/concepts/glossary/#runtime-harness), so it lacks the protections [Node.js Runtime](/cloud/backend-packages/nodejs-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](/cloud/backend-packages/schedule/#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](/cloud/guides/serve-a-web-client/#6-serve-the-files-yourself-in-a-local-run) 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_TOKEN`
- `TURNZERO_CLOUD_API`
- `TURNZERO_CLOUD_GATEWAY_URL`

If it reads any of them, use the provisioned run in [steps 1–4](#1-write-the-environment-file). Use those steps whenever the application needs platform services or shared development data.

This run is separate from [the platform's local run](#4-know-what-a-local-run-reaches) 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](https://pglite.dev/docs/pglite-socket) 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:

```sh
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](https://hub.docker.com/_/postgres):

```sh
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](https://www.postgresql.org/docs/current/app-pg-ctl.html). On Linux and macOS, give it a socket folder your user can write, such as `/tmp`:

```sh
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:

```dotenv
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](/cloud/guides/add-a-database/#commonjs-and-express) with:

```text
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](/cloud/reference/refusals/) 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](/cloud/concepts/glossary/#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](/cloud/troubleshooting/secrets/#the-provision-line-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](/cloud/concepts/turnzero-command/#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](/cloud/getting-started/deploy-an-application/) deploys the application once it runs on your machine.
- [Test your application locally](/cloud/guides/test-your-application-locally/) runs the tests over the test doubles, with no call to the platform.
- [The turnzero command](/cloud/concepts/turnzero-command/#running-on-your-machine) describes `provision` and `run`, and the forms `run` reads in the file.
- [Applications and environments](/cloud/concepts/applications-and-environments/#where-an-application-runs-during-development) compares the local run, the deployed development copy, and the tests.
- [Secrets](/cloud/troubleshooting/secrets/) in Troubleshooting covers a refused `provision` command and a shell value that wins over the file.
- [A deployed app's settings](/cloud/concepts/the-settings-a-deployed-copy-receives/) compares the settings a deployed copy reads with those in the local environment file.
