Ways to deploy to Turn Zero Cloud #

View this page as Markdown

This page is mainly for AI coding tools to use directly. It explains how to choose among the ways to deploy an app to Turn Zero Cloud.

Prefer the turnzero CLI where it works. Try command_npx first (command_npx_windows on Windows); no global install is needed. MCP deploy_files suits a first simple test app within its limits, even where the turnzero command installs. Where it works, switch to the turnzero command for binary files, a second deploy, an app the person keeps, scaffolding, or local runs; otherwise, use your judgment.

If npx is refused, run command if turnzero --version works. Otherwise use deploy_files within its limits, the upload route beyond them, or install. With no shell, use deploy_files alone and skip local runs and tests. Ask the person to run a command only when no other way works.

You do not need to identify your permission mode or network policy in advance. Try the recommended step; a refused npx command, install, authorization, or connection tells you which alternative to use. A tool may refuse the global install even when it permits npx. Your tool's permission to run a command is separate from the network access of the shell it runs in. A command your tool may run can still fail to reach turnzero.ai or the npm registry, and a shell with that access can still have the command refused.

Prerequisites #

Check that your Cloud connection is signed in. Create the application and submit its manifest as Deploy from your computer describes, regardless of the route you choose.

After submitting the manifest, call check_deploy before the first deploy and after each fix, whichever route you use. With a shell, run the command it returns to check your code too; deploy once nothing is refused.

Steps #

1. Choose the route your environment supports #

If you can do this	Route to use	If it cannot work
Run the `turnzero` command through npx or a global installation, and reach `turnzero.ai`	Prefer the returned npx form for regular use. A first simple test can use `deploy_files` within its limits.	If npx is refused, try the installed command when available. Otherwise, use `deploy_files` or install the command. If no command can run, use the upload route past `deploy_files`' limits.
Run CLI commands and access the `turnzero.ai` REST APIs, but cannot run turnzero through npx or a global installation	Use `deploy_files` within its limits, and the upload route past them.	Ask the person for the step you cannot perform if neither route works.
Run CLI commands, but cannot access the `turnzero.ai` REST APIs from that shell	Use `deploy_files` through the signed-in MCP connection, within its limits.	Explain the missing network access or size limit; ask the person for an available route.
Use the MCP connection but have no shell	Use `deploy_files` within its limits.	You cannot upload a ZIP yourself. Ask the person to deploy from a computer with a shell.
Run an automated pipeline with no AI or MCP connection	Use the `turnzero` CLI command with a preconfigured minted token, or the authenticated HTTP API.	Fix the missing credential, tool, or network access before retrying.

A desktop or cloud workspace follows the same table. For example, a workspace may reach turnzero.ai but not the npm registry. Within deploy_files' limits, use deploy_files. Past them, the upload route can still work through curl or PowerShell even though installing the turnzero CLI command cannot.

2. Deploy using that route #

Route	What it needs	Limits and details
`deploy_files` in one call	A signed-in MCP connection. Send the application's complete file list with file contents.	Text or binary files up to 512 KiB each, counted in decoded bytes; at most 200 listed entries; 4 MiB total, including filled library files. The JSON request also has a 4 MiB bound, so send a folder near that size in several calls.
`deploy_files` in several calls	The same connection. Send contents first, then the complete file list using the hashes in `kept`.	The same limits apply. Splitting calls does not raise the 200-entry limit on the final list.
The `turnzero` CLI command	A shell, Node.js 24 or later, access to the npm registry and `turnzero.ai`, and computer authorization or a minted token.	Zips and uploads the folder. Supports text and binary files.
The upload route	A signed-in MCP connection, and a shell that can ZIP the folder and run curl 7.76 or later, or PowerShell, with access to `turnzero.ai`.	Needs no Node.js, turnzero installation, or standing computer credential. Supports text and binary files.
Authenticated HTTP deploy	A script with access to `turnzero.ai` and a minted token kept outside the chat.	Uses the same ZIP deployment API as the `turnzero` command.
The person runs a command	Explain which step you cannot perform and give the person the exact command needed.	Use this after the available in-tool routes cannot complete the deploy.

For deploy_files, send text as content, or binary bytes as base64 in content with "encoding": "base64". The file limits count decoded bytes; base64 makes the request about a third larger. Leave out node_modules and the Turn Zero library package copies (lib/<name>) the platform fills. Filled library files count toward 4 MiB, but not the 200 listed entries. Follow Deploy from a chat for the file list, library versions, and successive calls.

For the turnzero CLI command, follow Authorize this computer for deploys, then Deploy from your computer. Try your call's command_npx first, or command_npx_windows on Windows.

For the upload route, declare a storage area if needed, call mint_upload_grant, run its curl or PowerShell upload line, then call deploy naming the stored ZIP as artifact. An upload grant from your tool gives the steps.

Every ZIP route has the same limits: at most 65,535 entries and 128 MiB of declared entry data. Each entry counts at the larger of its compressed and uncompressed sizes. Root package.json and manifest.json each have a 1 MiB limit. See the artifact refusals for the remaining checks.

During the deploy, the platform installs the runtime dependencies package.json names, not devDependencies, taking the versions package-lock.json records where they still meet the package's ranges. Leave node_modules out on every route, including a ZIP you make yourself. A ZIP still includes the Turn Zero library package copies your application imports; only deploy_files fills them from the library.

For a pipeline, prepare the application and its services beforehand. Store its minted token in the pipeline's secret store as TURNZERO_CLOUD_MINTED_TOKEN; never paste the token into chat. Deploy with nobody at the keyboard explains the setup; the deploy reference describes the HTTP forms.

When to ask the person #

Try the available routes before handing work back. Ask for one step at a time, explain what was refused and why, then wait for the result.

The MCP connection is not signed in: ask the person to sign in.
The install line or the upload's curl line is refused and no available route remains: give the person the install line, then the deploy line your own call returned, to run in their own terminal.
Authorization or the deploy line is refused and no available route remains: give the person that exact line to run in their own terminal.
You have no shell and the app is past deploy_files' limits: ask the person to deploy from a computer with a shell.
Your shell cannot reach turnzero.ai and the app is past those limits: explain that the deploy needs access to turnzero.ai; ask the person to provide an authorized environment or deploy from their own computer.
Node.js is below 24 on the person's computer: explain the required version and let the person decide whether to update it.

Never suggest changing your tool's permissions to bypass a refusal. Never ask the person to paste a token value into chat.

3. Read the result #

Read read_status with wait_seconds until the deploy ends, then check the health path and relevant routes. Use request_route when you have no shell.

If a response is lost or is not the platform's own, read status before repeating an action. A missing answer does not mean the deploy failed to start.

Expected result #

The deploy reaches deployed, and the application's health path succeeds. Report the version and hostname returned by the platform. If the deploy is still running or failed, report that state instead.

Refusals #

What you see	Cause	Remedy
`deploy_files_too_large`	The files are past `deploy_files`' limits.	Use the `turnzero` command where it works, otherwise the upload route. With no shell, explain the limit to the person.
Installation, authorization, or command execution refused	Your tool's own permission check refused the step.	Respect the refusal. Use another available route, telling the person which route and why; do not bypass the host's controls.
The shell cannot connect to `turnzero.ai`	The network the shell runs on cannot reach `turnzero.ai`.	Use the MCP route within its limits, or explain the network access the person needs to provide.
No valid sign-in or token	Your tool holds no signed-in connection, or this computer holds no token.	Follow Connect your AI coding tool.

Deploy troubleshooting starts from the failure you see, and Refusals lists the platform's named errors.