Run your application on your machine

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."

What your tool does

  • Calls submit_manifest with the application, its manifest, and local_run: true.
  • Runs the response's provisioning.command, or provisioning.command_windows on Windows, once, as given, in the application's folder. The line writes .env and prints no credential value.
  • Gives each setting your manifest binds a local value of its own, and sets PORT where your server requires it.
  • Starts the entry your start script runs with the environment file loaded, from a shell where no setting the file supplies is already set.
  • Requests the manifest's health path, and reports the address the application answers on.
  • Never commits .env.

What you need

Before your AI starts

This section is for your AI tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

  • Your tool connected and signed in (Connect your tool).
  • The application created and its manifest written, as steps 1 and 2 of Deploy an application describe.
  • .env listed in your ignore file, because the provision line writes credentials into it.

Steps

1. Write the environment file

Your machine can run the application under its development records, so local test data never lands in the live database. Your tool calls submit_manifest with the application, its manifest, and local_run: true. It runs the response's provisioning.command, or provisioning.command_windows on Windows, once, as given, in the application's folder, before provisioning.expires_at, five minutes after the call.

The line reads echo <grant> | npx -y <address> provision --application <application id>. It replaces each of the two development credentials once with a new value, and writes .env, or the file --env-file names. A second run needs a new line from a new submission naming local_run. Running on your machine describes it. Development's deployed copy keeps the revoked credentials until you deploy or restart it.

2. Read the settings the file holds

The application reads the file's seven settings at start:

  • APP_DATABASE_URL, the development database's connection string, built from the connection facts and the new password with sslmode=verify-full;
  • APP_DATABASE_CONNECTION_LIMIT, the plan's connection_limit, the client pool's maximum, as a deploy sets it;
  • TURNZERO_CLOUD_TOKEN, the development platform credential;
  • APP_ENVIRONMENT=local, the log stream a local run writes;
  • TURNZERO_CLOUD_API=https://turnzero.ai, the platform origin the application's sign-in and account reads use;
  • TURNZERO_CLOUD_GATEWAY_URL=https://turnzero.ai, the origin the storage, logging, and external-API calls use, which the platform handles at the same address;
  • TURNZERO_CLOUD_APPLICATION, the application's identifier, as a deploy sets it.

An application whose manifest declares no database kind has neither APP_DATABASE_URL nor APP_DATABASE_CONNECTION_LIMIT, and the line writes the other five. An application that reads none of these settings runs on your machine without the line. A hosted deploy never needs it.

3. Start the application

Start the entry your start script runs with the environment file loaded, for example node --env-file=.env src/main.mjs for the project step 3 of Deploy an application shows, and never commit the file. Two settings need care on your machine:

  • PORT: a deployed copy receives it from its image, and the line writes none, because the port is your application's own. Set it for the local run, for example PORT=3000 in the shell or a line of your own in .env, unless the server falls back to a port of its own. A server that requires PORT does not start without it.
  • A variable already set in your shell wins: node --env-file keeps it and ignores the file's line. A TURNZERO_CLOUD_TOKEN left in the shell from another project would reach the platform in place of the file's credential. Before the run, unset in the shell each setting the file supplies, or start from a new shell.

A setting your manifest binds to a stored secret gets no line from the provision line, because no call returns a stored value. Put its local value on a line of your own in .env, which the provision line 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.

4. Know what a local run reaches

Under the development platform credential, every call the local process makes is a development call:

  • A file write is stored in the development partition of its area.
  • A log line goes to the local stream, which read_logs reads with environment: "local".
  • A call to a declared upstream goes through the public gateway, which applies the development key value, so your machine has no provider key.

An end-user session is verified through the platform's verification route, POST /accounts/v0/verify, under the development platform credential, and not on your machine. The environment file contains no realm keys. Local verification would also need a header the serving router adds, which never reaches a process outside the platform, so keys in the file would change nothing.

On one environment, testers sign in on production's realm at <label>.ai.host/__account/ during a local run too, as end users of the live application. With development on, they sign in on the development realm.

The local process reaches the development database over the server's public endpoint under the platform's developer network rule. A local run loads no runtime harness. The Node.js Runtime package says which protections only a deployed copy receives. Applications and environments compares the local process, the deployed development copy, and the tests over the doubles.

Expected result

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.

Refusals

The provision line's refusals come from its secret grant. The provision line is refused gives the check for each.

Refusal Status Cause Remedy
secret_grant_spent 403 The line already ran, or someone else used a copy of its grant first. Call submit_manifest from your tool again with the application, its manifest, and local_run, and run the line it returns as given.
secret_grant_expired 403 The line ran after its expires_at. Call submit_manifest from your tool again with the application, its manifest, and local_run, and run the line it returns as given.
secret_grant_not_admitted 403 The line was changed, for example to give another --application. Call submit_manifest from your tool again with the application, its manifest, and local_run, and run the line it returns as given.