Deploy with nobody at the keyboard #

View this page as Markdown

Prompt:

Build this app and deploy it to Turn Zero Cloud. Nobody will be at the keyboard.

Also works:

  • "Work unattended: build it, test it, and deploy it when you can."
  • "The connection says Needs authentication, and nobody is here to sign in."
  • "How does an agent deploy with no person available?"

A person signs in once, in a browser, before any deploy. There is no headless first sign-in. Until then, every call to Turn Zero Cloud's tools answers with a sign-in request and does nothing. The deploy line has no credential to run under either, so it sends nothing. With nobody at the keyboard, your tool does the work that needs no sign-in, then stops with one ask. After that one sign-in, or a token you mint, later sessions deploy with no person.

What your tool does #

  • Builds the application and runs its tests on this computer, with no sign-in (step 1).
  • Writes manifest.json and makes the folder ready for the deploy line (step 2).
  • Reads these pages on the web, since its documentation tools wait for the sign-in too (step 3).
  • Stops with one message that says what it built and asks for the sign-in (step 4).
  • Never signs in for you (Set up Turn Zero Cloud with your AI, step 2).
  • After the sign-in, authorizes this computer itself and tells you. Under a minted token, it sets TURNZERO_CLOUD_MINTED_TOKEN for one turnzero line at a time (step 5).
  • Where nobody can be asked, starts a new application on the Free plan and says so, and stops and reports rather than promote.

What you need #

  • A web browser, for the one sign-in. Your first sign-in creates your free Turn Zero account.
  • For the token route, your own AI coding tool signed in to Turn Zero Cloud, and a safe place to keep the token, such as a pipeline's secret store.

Before your AI starts #

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

  • Whether Turn Zero Cloud's tools answer in this session. In Claude Code, claude mcp get turnzero-cloud shows the server's status. Needs authentication there, or a call answered with a sign-in request (status 401), means nobody has signed in yet.
  • Whether this computer holds a token: turnzero whoami names the account it acts as. Where the computer holds none, it sends nothing and prints the login route.
  • Whether a minted token is kept where your tool can read it, such as a variable it can name.
  • Node.js 24 or later, and npm, for the local build and the tests (What your computer needs).

Where the tools answer, this computer holds a token, or a minted token is set, nobody needs to sign in. Deploy as Deploy an application says.

Steps #

1. Build and test locally #

Build the application and run its tests on this computer. Neither needs a sign-in.

A new project starts from the hello-world template, with turnzero scaffold at the project's root. The line writes the service, installs it, and tests it. A hello-world run reads no credential and sends no request. The other templates take packages from the library, which needs this computer's token. From version 0.25.5 of the command, without one, they write nothing and end with status 3.

Run the tests offline, as Test your application locally describes. Each package the project already holds under app/lib/ gives its test double from @turnzero/<name>/testing. The tests then need no account, no connection, and no environment file. Taking a new package from the library needs a token, so a package the project lacks waits for the sign-in.

2. Make the folder ready #

The deploy line zips the application's folder, the folder whose top holds package.json (What the deploy zip holds). Before the sign-in, make that folder ready:

  • Write manifest.json in the folder, as Author the manifest shows. Every member is required. A hello-world run writes app/manifest.json itself.
  • Leave the manifest's application member out. The first deploy writes it and prints a bound: line.
  • Give package.json a start script. The image build installs the dependencies with npm install --omit=dev, then runs npm start.
  • Have the server answer status 200 at the manifest's health path, which each deploy's health check requests.

Then run turnzero hash in the folder. It builds the same zip a deploy would, sends nothing, and prints the same folder warnings, with no sign-in.

3. Read the pages on the web #

Turn Zero's production site is public, so every page here reads with no sign-in. A page's Markdown copy is at the page's address followed by index.md. For example:

curl -s https://turnzero.ai/cloud/getting-started/deploy-an-application/index.md

The index of every page is at https://turnzero.ai/cloud/llms.txt, and the whole text at https://turnzero.ai/cloud/llms-full.txt. read_documentation and the other tools wait for the sign-in.

4. Stop with one ask #

Your tool ends the session with one message for you to act on when you return. It says what it built, that the tests pass, and that the deploy waits only on the sign-in. It then names the two routes and where each is done:

  • (a) Sign the tool's connection in, on its computer. In Claude Code, you type /mcp, choose turnzero-cloud, and sign in in the browser it opens. You can also run claude mcp login turnzero-cloud in a terminal of your own. In Codex, you run codex mcp login turnzero-cloud.
  • (b) Mint a token from your own signed-in tool. You mint it as Mint a token shows. You run its token claim line in a terminal of your own, piped into the store your tool's environment reads.

A sample of the message, for your tool to copy with its own facts in the angle brackets:

I built <the application> in <folder>, and its tests pass on this computer: <count> tests. The deploy waits only on a sign-in to Turn Zero Cloud, which only you can make, in a browser. Choose one:

(a) On this computer, sign my connection in. In Claude Code, type /mcp, choose turnzero-cloud, and sign in. In Codex, run codex mcp login turnzero-cloud.

(b) From your own AI tool, signed in to Turn Zero Cloud, mint a token, and keep it where I read TURNZERO_CLOUD_MINTED_TOKEN. The steps are at https://turnzero.ai/cloud/guides/mint-a-token/.

Then start a new session here, and it deploys.

5. Deploy after the sign-in #

On route (a), the sign-in is saved for this computer, so a new session in any folder is signed in too. Your tool creates the application and submits the manifest, as Deploy an application says in its steps 1 and 2. It then authorizes this computer itself, with authorize and one mint_token call. It tells you the token's label, its 30-day expiry, and how to revoke it (Authorize this computer for deploys).

This computer's token lasts 30 days. Authorizing the computer again renews it: your signed-in tool's authorize, or your own turnzero login. The connection itself renews without another sign-in, and ends after 60 days without a renewal (The tool's connection).

Route (b) needs an application that already exists, made from a signed-in session as Deploy an application says in its step 1. Your tool then sets TURNZERO_CLOUD_MINTED_TOKEN from where the token is kept, for one turnzero line at a time. It never writes the value in a line. It runs the deploy line under it, turnzero deploy --application <application id>, as Deploying unattended shows. Connected by a minted token, it cannot call mint_token, so it cannot authorize this computer.

A minted token's scope is set at minting: the whole account, or one application your account already has. It lasts until the expiry its mint set, from 1 to 3650 days. Minted with no expiry, it does not expire. revoke_token ends it early.

After route (a), or route (b) for an application that already exists, each later deploy is one call, one line, and one read, with no person (The deploy in one pass).

Expected result #

  • The session with nobody at the keyboard ends with the application built, its tests passing, and manifest.json in its folder. Its last message is the ask, naming the two routes.
  • After route (a), claude mcp list lists the MCP server, turnzero-cloud, as connected, and your tool says it authorized this computer.
  • After route (a), or route (b) for an application that already exists, the deploy line ends with settled: deployed version 1 and status 0, and the version serves.

Refusals #

This table lists the refusals these steps most often meet; the refusals page lists all of the platform's refusals, with the cause and remedy of each. A backend package's own failures are listed on its package page.

What you see Cause Remedy
Needs authentication in claude mcp list Nobody has signed in yet. Stop with the ask in step 4.
authentication_required, status 401, from a tool call The connection presented no credential, or one that resolves to no account. Nothing was done. Stop with the ask in step 4. Once you sign in, your tool makes the call again.
claude mcp login fails with "stdin isn't a terminal" The login needs a terminal, and an AI's shell isn't one. Don't retry it. You sign in with /mcp in a session, or run the login in a terminal of your own.
The deploy line prints the login route and ends with status 3 This computer holds no live token, and TURNZERO_CLOUD_MINTED_TOKEN is not set. The command sent nothing. Stop with the ask in step 4, then run the same line once a route is done.
The deploy line ends with status 3 under an empty TURNZERO_CLOUD_MINTED_TOKEN The variable is set but empty, or holds only spaces. The line sent nothing. Set it from where the token is kept, as Setting the variable for one line shows.
session_credential_required, status 403, from mint_token mint_token was called under an account-scoped minted token. A token cannot mint another token. Mint from a signed-in session, as route (b) does.