What happens without asking #
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 otherread_andlist_actions, andquery_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_libraryandread_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.
deployplaces 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 withcreate_environment, a deploy goes to development instead. - Promotes and rollbacks. With development turned on, production changes through
promote.roll_backputs an earlier production version back, on one environment or two. Both change what your users see. - Manifest submissions.
submit_manifestrecords 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_secretstores a value by name; addreplace: trueto replace it.revoke_app_sign_in_keysrevokes 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_areaanddeclare_outbound_api,mint_tokenandrevoke_token,run_schedule,request_route,write_route, and the invitation and end-user actions other thandelete_end_user. To resume a halted environment, callhalt_environmentwithresume: true.add_test_end_userswithremove: trueremoves test end users at once, with no approval, anddeclare_storage_areaanddeclare_outbound_apiwithremove: trueremove what they declared.request_routesends one request to a route of your own application, and a method other thanGET, such asPOST,PUT,PATCH, orDELETE, 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_readwithack: truemay omit deliveries acknowledged by the first call. Uselastwithchannelto read that channel's recent messages, whether acknowledged or not. tzmesh_send: repeat the call with the sameclient_idso the message is sent once.deploy,deploy_files,promote,roll_back, andrestart_application:read_statuswithwait_seconds.run_schedule:read_schedules, and repeat the call only with the samerequest_id.- Another reversible action: read what it changes before repeating it, such as
list_secretsforstore_secretandread_app_sign_inforconfigure_app_sign_in.
Some actions start work that goes on after the call returns:
- When your AI tool's
deploy_commandcall returns 200 withstate: "awaiting_command", it has started no deploy. On a hosted connector's session, itsdetailnames thedeploy_filescall to make with your folder's files added. Every other caller gets the command to run. - The command's own
deploycall andpromotereturn 202 withstate: "deploying"andnextonce their checks pass, and the work continues on the platform. Withwait_seconds, the response waits while the work runs. It is 200 withdeployedorfailedwhere the work ended within the wait, and otherwise 202 withnext. Read the result withread_statusorlist_versions. run_schedulestarts a run and returns the run's current record, while the scheduled job may still be running. It requiresrequest_id: repeating that identifier returns the run the first call started, or starts it where the first call did not. Withwait_seconds, the response waits while the run runs, andsettledsays whether the record it returns has ended. Where it has not,read_schedulesreports 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
restartrow 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_tokensno longer lists the token, and arevoke_tokencall for it returnsnot_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_applicationremoves every environment of the application and everything that belongs to them.delete_environmentremoves 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_userremoves one end user's identities, sessions, passkeys, and user record.delete_secretremoves one stored secret's entry; the secret store keeps the deleted value for ninety days before it purges it.delete_spacedeletes one issue space your account owns, with its issues and its daily copies, and ends every application's binding to it.redact_issue_textreplaces 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_databasedrops the development database and creates it again empty under the same role; the credential stays valid.purge_logserases an application's log entries and counter totals before their retention period ends.rename_applicationpermanently 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_manifestwithholds both values and returnscredentials: "withheld". - Through the MCP tool,
store_secretwithreplace: trueon either of those two names is refusedlocal_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.
Related #
- 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.