What happens without asking #

View this page as Markdown

On this page

Management actions have three tiers: observe, reversible, and destructive. Observe and reversible actions run through your AI tool without browser approval. Destructive actions, such as delete_application, wait for you to approve a link in your browser.

The tier controls approval, not whether an action can be undone.

What completes on your request alone #

Your AI tool can perform observe and reversible actions as part of your request. Some finish immediately; others start work that continues after the call returns.

  • Reads. The observe tier reads state without changing it: read_status, read_logs, list_versions, list_secrets, read_usage, the other read_ and list_ actions, and query_database, which reads an environment's database inside a read-only transaction. Each needs a sign-in or a token of your account. Two reads, read_library and read_context, accept a sign-in or token from any account, including a suspended account. They still require a credential (The AI tool's connection).
  • Deploys. deploy places a built artifact in the environment a deploy goes to. On a new application that is production, so a deploy changes what your users see. Once you turn development on with create_environment, a deploy goes to development instead.
  • Promotes and rollbacks. With development turned on, production changes through promote. roll_back puts an earlier production version back, on one environment or two. Both change what your users see.
  • Manifest submissions. submit_manifest records the manifest and provisions the services it declares, such as the development database and an end-user realm for each environment.
  • Secrets and keys. store_secret stores a value by name; add replace: true to replace it. revoke_app_sign_in_keys revokes a realm's signing keys, and every user of that realm then signs in again.
  • The other reversible actions. These include create_application, set_app_size, halt_environment, restart_application, configure_app_sign_in, declare_storage_area and declare_outbound_api, mint_token and revoke_token, run_schedule, request_route, write_route, and the invitation and end-user actions other than delete_end_user. To resume a halted environment, call halt_environment with resume: true. add_test_end_users with remove: true removes test end users at once, with no approval, and declare_storage_area and declare_outbound_api with remove: true remove what they declared. request_route sends one request to a route of your own application, and a method other than GET, such as POST, PUT, PATCH, or DELETE, can change your application's data.

Reversible means the action runs without an approval step. It does not mean a second call undoes the first. Retry behaviour belongs to each action: do not assume that repeating a call has no further effect, or that the tier offers a general undo. A transport or gateway error may be transient and does not show whether the call ran. Use the retry rule below.

The next step depends on the call:

  • A read: repeat it at once. A repeated tzmesh_read with ack: true may omit deliveries acknowledged by the first call. Use last with channel to read that channel's recent messages, whether acknowledged or not.
  • tzmesh_send: repeat the call with the same client_id so the message is sent once.
  • deploy, deploy_files, promote, roll_back, and restart_application: read_status with wait_seconds.
  • run_schedule: read_schedules, and repeat the call only with the same request_id.
  • Another reversible action: read what it changes before repeating it, such as list_secrets for store_secret and read_app_sign_in for configure_app_sign_in.

Some actions start work that goes on after the call returns:

  • When your AI tool's deploy_command call returns 200 with state: "awaiting_command", it has started no deploy. On a hosted connector's session, its detail names the deploy_files call to make with your folder's files added. Every other caller gets the command to run.
  • The command's own deploy call and promote return 202 with state: "deploying" and next once their checks pass, and the work continues on the platform. With wait_seconds, the response waits while the work runs. It is 200 with deployed or failed where the work ended within the wait, and otherwise 202 with next. Read the result with read_status or list_versions.
  • run_schedule starts a run and returns the run's current record, while the scheduled job may still be running. It requires request_id: repeating that identifier returns the run the first call started, or starts it where the first call did not. With wait_seconds, the response waits while the run runs, and settled says whether the record it returns has ended. Where it has not, read_schedules reports the job's final outcome. Every response is 200.

A response's next gives the call to make with every argument filled in. An action that can return several calls uses a list, even when it returns only one; otherwise, it uses one object. Make each call as given. A pending action needs the person's approval next, so its response has no next.

Two limits apply to reversible actions:

  • Halting production needs your signed-in session or a token minted for the whole account. A token bounded to one application is refused 403 account_credential_required.
  • A minted token acts only within the scope and the grants it received when it was minted (Sign-in, sessions, and tokens).

Some skills also ask you first where the choice is yours. The skill:deploy and skill:move-existing-app skills ask which size a new server starts on. Where nobody can be asked, they start it on Shared 0.5 GB and say it draws the account's Free Allowance. For a site of static files alone, follow Publish a static site, with no size to choose. The skill:update-library skill asks before it updates each library entry.

Both skills follow the project's stated audience: visitors, customers or anyone mean public; a team, company or invited people mean invited. With no audience stated and nobody to ask, they choose and report public, except invited for a server without its own sign-in.

For that server, they explain that the code checks no caller and how to open access. For a static site, they choose public, report that anyone can reach it, and say how to restrict it: set the manifest's audience to invited, call submit_manifest, and deploy as required.

The catalog also lists actions the running platform does not provide: the tool list leaves them out, and a call to one returns 501 not_yet_provisioned. Actions reserved for platform staff appear in neither the public catalog nor a customer's tool list. On the HTTP API, a call without the required grant is refused 403 grant_required, which the refusals page explains.

What the platform does on its own #

The platform also performs these maintenance tasks:

  • It halts a development environment at its daily check once seven days have passed since its serving version's deploy or its last resume, whichever is later (Halts the platform makes).
  • It re-creates an environment's running copy after it changes the router mark, writing a restart row in the version history.
  • Once a day it deletes older versions' images, keeping the images of each environment's twenty most recent deployed versions, the serving version among them (The version history).
  • Once a day it also deletes the record of a token revoked or expired more than thirty days earlier. After that, list_tokens no longer lists the token, and a revoke_token call for it returns not_found. Mint a token describes the listing.
  • Every ten minutes it removes each test end user whose 48 hours have passed, and the sessions that user opened end with it. A test end user holds no person's data.

These tasks preserve application declarations and production user data. Expired test users and their sessions are removed.

The platform does not move a running version onto a newer base image. A new deploy of a server uses the current base image, which can include security fixes. With one environment, that deploy updates production. With development turned on, deploy to development, then promote that version to bring its base to production.

A promote, a rollback, or a restart keeps the selected version's image. The base member of each environment in read_status says whether a new deploy would use a newer base and how severe the fixes are.

What asks first #

A destructive action completes only after a person approves it in a browser. Calling one creates a pending action and returns the platform's description of the change with an approval link. Your AI tool prints the link and reads the outcome with read_approval_status.

The destructive actions:

  • delete_application removes every environment of the application and everything that belongs to them.
  • delete_environment removes the development environment alone, and the next deploy goes to production.
  • Account deletion, requested on the website’s Account & security page, deletes every application the same way, then ends the account’s services. Your AI tool cannot request it.
  • delete_end_user removes one end user's identities, sessions, passkeys, and user record.
  • delete_secret removes one stored secret's entry; the secret store keeps the deleted value for ninety days before it purges it.
  • delete_space deletes one issue space your account owns, with its issues and its daily copies, and ends every application's binding to it.
  • redact_issue_text replaces selected text with [redacted] or removes an image from an issue space. It leaves earlier text in history unchanged (Redact text or an image).
  • clear_development_database drops the development database and creates it again empty under the same role; the credential stays valid.
  • purge_logs erases an application's log entries and counter totals before their retention period ends.
  • rename_application permanently retires both of the application's hostnames, production's and development's.

Your AI tool can request the listed actions except account deletion, which you request on the website’s Account & security page. A minted token needs the destructive grant for an action it may request, and even with the grant it cannot approve.

The pending action #

Calling a destructive action asks for approval; it does not run the action. The platform creates a pending-action record and returns its description of the proposed changes, with an approval link. A signed-in person of the requesting account approves or declines on the platform's browser page. No tool, resource, prompt, or token can approve an action. read_approval_status, given the returned record identifier, reads the record's state and outcome.

Supply your own request_id so a retry is recognised. For the same requesting account and action, a repeated identifier returns the existing record while that record is live: requested and not past its 24-hour expiry, approved, or executing. Without an identifier, each call creates a new record.

When the subject changes before approval #

The subject can change between the request and the approval, for example after a deploy or a change to an application's storage. At approval, the platform describes the subject again and compares the two descriptions. If they differ, the record ends declined with the outcome description_changed, both descriptions are returned, and the action does not run. To go ahead, request the action again and approve its current description.

If the application itself is gone by then, deleted by an earlier approval, the approval page says it is already deleted or being deleted and that nothing is left to approve. A rename's page says the application is no longer in your account.

What runs after approval #

The action runs as the approved description says. After approval, the platform runs the action using the saved subject, input, and state used to prepare the description. It never uses a fresh reading of the subject to choose what to act on. rename_application takes the hostname it retires from the approved description. If another rename or a deletion changed the application after the approval, the rename changes nothing and returns renamed: false with the reason.

When execution is interrupted #

If execution is interrupted, the record can stay executing. A recovery pass runs when the service starts and every ten minutes. It marks a record that has been executing for more than thirty minutes as failed, with the outcome interrupted.

That outcome does not prove that nothing changed before the interruption. Read the record and check the current subject before you retry. A new request after a failure creates a new pending action; give it a fresh request_id to tell the attempts apart. Every new attempt still needs a person's approval in the browser.

What the tool never sees #

An application's development database credential and development platform credential reach your machine only over the HTTP API, never through the Model Context Protocol (MCP) tool:

  • Through the MCP tool, the first submit_manifest withholds both values and returns credentials: "withheld".
  • Through the MCP tool, store_secret with replace: true on either of those two names is refused local_route_required.
  • Instead, for a run on your machine, the AI tool runs turnzero provision --application <application id> with nothing piped, makes any call it prints, and runs the provision command that call returns. The command carries no credential. It re-mints the local run's platform credential, and its database credential if the manifest declares a database, over the HTTP API under a grant claimed with this computer's verifier. It writes the values into the environment file without printing them.

The platform never returns a production credential to anyone.

No management action reads a stored secret back. list_secrets returns names, scopes, and timestamps, and list_tokens returns token records without values. For its value argument, the store_secret tool takes only a value you already put in the conversation, with or without replace: true. No other value passes through a tool call. Any other call returns a command line, which Store a secret describes. The command sends the value from your machine over the HTTP API, keeping it out of the conversation. A store_secret call naming generate creates the value in the secret store and returns no command.

A minted token's value reaches no tool either: mint_token returns a command, and the value goes once to your own terminal or to the computer's credential file (Mint a token).

An invitation URL is single-use. invite_end_user with email returns it to your AI tool once, and list_invitations never returns it again. The platform does not email an application's invitations, so send the URL to the person yourself.

What is recorded #

Every action writes a record that is never changed afterwards. It contains the actor, the credential used, the action, its subject, the outcome, and any confirmation. The record names the credential's kind, and the credential itself where it has an identity of its own, as a token does and a browser session does not. Check the result for completion or failure; an action that starts background work also reports how to read its outcome.

  • Sign-in, sessions, and tokens explains each credential, what it may do, and what ends it.
  • Mint a token mints a token bounded to the account or to one application, with the grants it needs.
  • Manage versions and environments deletes the application or its development environment and renames it, each through the approval.
  • Store a secret gives the command line that sends a value.
  • The turnzero command gives the command that writes the development credentials into the environment file.
  • Actions lists every management action a customer can call, with its tier, inputs, and outputs.