---
title: Ways to deploy to Turn Zero Cloud
description: Choose a deployment route for your AI coding tool, from a first small test through regular development and automated releases.
slug: /getting-started/ways-to-deploy
order: 3
visibility: public
redirects_from: [/getting-started/ways-to-deploy-to-turn-zero-cloud]
---

# Ways to deploy to Turn Zero Cloud

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](/cloud/getting-started/connect-your-tool/). Create the application and submit its manifest as [Deploy from your computer](/cloud/getting-started/deploy-an-application/) 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](/cloud/getting-started/build-an-app-from-a-chat/) for the file list, library versions, and successive calls.

For the `turnzero` CLI command, follow [Authorize this computer for deploys](/cloud/getting-started/connect-your-tool/#authorize-this-computer-for-deploys), then [Deploy from your computer](/cloud/getting-started/deploy-an-application/). 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](/cloud/guides/store-files/#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](/cloud/getting-started/deploy-an-application/#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](/cloud/guides/deploy-with-nobody-at-the-keyboard/) explains the setup; the [deploy reference](/cloud/reference/actions/deploy/) 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](/cloud/getting-started/connect-your-tool/).
- **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](/cloud/getting-started/connect-your-tool/). |

[Deploy troubleshooting](/cloud/troubleshooting/deploys/) starts from the failure you see, and [Refusals](/cloud/reference/refusals/) lists the platform's named errors.

## Related

- [What your computer needs](/cloud/getting-started/prerequisites/).
- [Deploy from your computer](/cloud/getting-started/deploy-an-application/).
- [Deploy from a chat](/cloud/getting-started/build-an-app-from-a-chat/).
- [How the command finds its credential](/cloud/concepts/how-the-turnzero-command-finds-its-credential/).
- [Deploy with nobody at the keyboard](/cloud/guides/deploy-with-nobody-at-the-keyboard/).