Glossary

This page defines each term the Turn Zero Cloud documentation uses, and it defines each term once. Every other page uses the word defined here, so read this page when a page uses a word you do not know. Each entry gives a short definition and links to the page that explains the term in full.

The entries are grouped by subject, under the headings below.

The application and its environments

Application

An application is the record Turn Zero Cloud keeps for your deployable code and the services it uses. It has a manifest and one environment, production, or two, development and production, each with its own managed hostname. create_application creates it with a name and a plan, free, standard, or pro, and it belongs to the account that created it.

Environment

An environment is one hosted copy of an application, production or development, each with its own hostname, secrets, stored files, and version history. A new application has production alone, and a deploy reaches it. create_environment adds development: a deploy then reaches development, and a promote moves a version to production. What submitting does says when each environment gets its database and its platform credential.

Running copy

An environment's running copy, also called its deployed copy, is the compute on the platform that runs the environment's serving version. A deploy, a promote, and a platform redeploy, such as one restart_application starts, each replace it with a new one and set its settings then. A running copy keeps the settings it started with until it is replaced. Settings and environment variables a deployed copy receives lists them.

Local run

A local run is your application running on your own machine under the development records every application keeps, whether it has one environment or two. It uses the environment file that the turnzero-cloud command's provision line writes. A submit_manifest call that names local_run returns the line. It reaches the development database under the developer network rule, presents the development platform credential, and writes the local log stream. On one environment its testers sign in on production's realm, the application's only list of end users. Applications and environments compares it with the deployed copy and the tests.

Manifest

The manifest is the JSON document that declares an application's services, health path, region, outbound hosts, audience, and library entries. submit_manifest records it and provisions each declared service the platform provides today. The manifest explains its members.

Audience

The audience is the manifest member that sets who may reach an application: public, invited, or workforce. A public audience lets anyone reach it. Under invited or workforce, the serving router refuses a request that has no end-user session, except a scheduled run and a path listed in session_free_paths. The audience kinds explains each kind.

Setting

A setting is a named value the platform places in a deployed copy's environment, which your code reads from process.env. The platform sets its own, such as TURNZERO_CLOUD_TOKEN. The manifest's settings member binds a stored value to a setting you name, and the platform then places that value in the copy. A declared upstream's settings add a base-URL setting and an egress key. Deploy an application lists every setting.

Hosting cell

A hosting cell is the set of platform servers and the cluster that host an application's environments and its databases. read_status reports an application's cell. Environments states how the development environment is placed in its cell.

Hostname label

The hostname label is the first part of an environment's managed hostname: the application's label for production, as in <label>.ai.host, and <label>-dev for development. The domain after the label is ai.host on the platform at https://turnzero.ai and dev.ai.host on Turn Zero's development platform, as The development hostname says. Renaming the application gives it a new label, which changes both hostnames. The emailed sign-in code and the passkey notices show the hostname label in their subject.

Grain and development group

An environment's grain is the way its compute runs, which list_applications and read_status show in grain. A container is compute that belongs to the environment alone, and production always runs as one. A pod is one of many development environments in a development group, a shared set of pods on the hosting cell's cluster, which keeps an idle development copy cheap.

Development runs as a container where the cell has no group open to new environments. A deploy into a group that is full is refused 409 group_full. The grain_note of read_status says in one sentence what each environment's grain means. Where each environment runs explains the placement.

Halted environment

A halted environment keeps its deployed version, its data, its credentials, and its schedule declarations, and serves nothing. Its hostname returns 503 environment_halted on every path, and its schedules do not fire. halt_environment halts an environment. resume_environment ends the halt, and a deploy also ends a development halt.

Where development is turned on, the platform halts it itself after an interval, currently seven days. The interval runs from the later of two times: the end of the deploy that made the environment's serving version, and its last resume. The platform never halts production. The halted state states the full rules.

Releases

Artifact

An artifact is the zip of your application's built code that a deploy installs and runs. Its root contains package.json, with a start script or a root server.js, and the platform installs its runtime dependencies. The turnzero-cloud command builds and uploads it. A script of your own can instead upload it to a storage area and name it in deploy's artifact member. Build and upload the artifact states the zip's rules.

Deploy

A deploy places a built artifact in an environment as a new version in the application's history. From your tool, it takes one deploy call and the line the call returns. The line runs the turnzero-cloud command, which zips the folder, uploads the zip, starts the deploy, and waits for it. Where the command returns first, the read_status call the response gives reads the rest, waiting up to 45 seconds with wait_seconds before it responds. The environment switches to the new version only once its health path responds, so a failed deploy leaves the running version serving.

A deploy goes to production on an application with one environment, and to development once development is turned on.

Upload

An upload sends your built zip to the platform and starts its deploy. A deploy call that names neither artifact nor upload returns the state awaiting_command and one line to run, which carries a one-time deploy code. It also returns the read_status call to make where the command returns before the outcome. Your tool runs the line in its own shell, once.

The command zips the folder and presents the code to prepare the upload, which returns a short-lived upload grant to the command alone. The zip is written to the application's deploy area under that grant, the same grant then starts its deploy, and the command waits for that deploy, printing each step and the outcome. Deploy an application describes the call and the line, and the turnzero-cloud command the command.

Deploy code

A deploy code is a short-lived credential for one deploy of one application. A deploy call from your tool returns it inside the line that runs the turnzero-cloud command, in that line's two forms, command and command_windows. The command reads it on its input and presents it once, to prepare the upload, and that use spends it.

The code ends at the response's expires_at, five minutes after the call at most. A later deploy call for the application also ends it, and that call's previous_code says what became of it. Until the code ends, the line is a credential: run it once, as given, and paste it nowhere. A code that cannot be used is refused 403 deploy_code_refused. A job with no tool deploys under a minted token instead, with no code. Sign-in, sessions, and tokens states what else ends a code.

Health check and health path

The health path is the manifest's health member: a path on your application's own server that responds 503 while the application starts, never a 4xx, and exactly 200 once it is ready. The health check is the platform's test of a new running copy at every deploy, promote, and platform redeploy.

The check requests the health path every three seconds for up to 180 seconds. The environment switches to the new copy only when the path returns 200, so a failed check leaves the earlier version serving. The version's outcome.gate then records the check's evidence. The health check gives every figure.

Control probe

A control probe is one request without the router mark that the platform sends to a new copy during its health check, to learn whether your own process is responding. It is sent at the check's deadline, or right after twenty probes in a row return the same 4xx status other than 408, 425, or 429. Where your process is running, its runtime harness refuses the control probe and writes one harness_refusal line to the console. A response from your own process after those twenty probes ends the check early.

Promote

A promote applies a version from the history to the production environment, with production's own settings and credentials. It reuses the image the deploy built and mints a new production platform credential. Production switches to the new version only after its health check passes. Only an application with development turned on promotes; on one environment the deploy already reaches production.

Roll back

A roll back puts an earlier version back in production, run as a promote of that version, on one environment or two. roll_back moves code only. The platform takes no snapshot at a deploy or a promote, so across a data-model change you decide how the data is migrated or restored.

Platform redeploy

A platform redeploy re-creates an environment's running copy with the same version and image. It applies the platform's current settings, and re-applies the bound values the copy was started with, never the current manifest's. restart_application starts one. The platform starts one itself after it changes the router mark, and a rename restarts each running copy. Each writes a restart row in the version history, and the health check runs again.

Version history

The version history is the application's record of every deploy, every promote, and every platform redeploy, one row each. list_versions returns it newest first. The deploy allocates each version number once per application, from one sequence that development and production share, and a promote row has the number of the version it promotes. An environment's serving version is its newest deployed row that an environment deletion did not retire. The version history lists each row's members.

The account and its people

Account

An account, your Turn Zero account, belongs to one person, and each application belongs to the account that created it. During the private beta, the first successful sign-in with an invitation creates the account. read_account identifies the connected account and its standing, active or suspended. Connect your tool covers your first sign-in.

Standing

An account's or an end user's standing is active or suspended. Platform staff suspend and reinstate an account, and revoke_end_user and reinstate_end_user do the same for an end user. A suspension ends every session of that account or user and refuses what needs its identity until a reinstatement. Two other members share the name: an invitation not yet used has the state standing, and list_library gives each entry a standing that compares your copy with the published library. Read the standing covers your account.

Builder

A builder is a person who has an account and builds applications on the platform. Builders belong to the platform's own realm, the builder realm, which is separate from every application's end-user realm. During the private beta, a builder account is created by an invitation that platform staff issue.

End user

An end user is a person who uses your application. An end user has no Turn Zero account: their end-user account belongs to the application's own realm in the accounts service. A person who signs in on the application's hostname has a session in that realm, and that session authorizes no platform management action.

Realm

A realm is a separate group of users in the accounts service. Builders belong to the builder realm. An application that declares the accounts service has one end-user realm per environment it has: production's alone on one environment, and a development realm too once development is turned on. A realm keeps its own users, identities, sessions, passkeys, invitations, and event log.

Sign-in method

A sign-in method is one way to sign in that a realm offers, such as google, github, an emailed code, or passkey. A passkey is a faster way to sign in by emailed code, so a realm offers passkey only beside the code. configure_realm sets a realm's sign-in methods in its member sign_in_methods. These pages also call one method a route, as in the work-account route; such a route is not an HTTP route of your application.

Creation policy

A realm's creation policy, its creation setting, sets whether a first sign-in creates an end user. open creates one for anyone who signs in, and invited only for a person with an invitation from issue_invitation. An invited audience makes every realm of the application invitation-only, whatever the setting is. configure_realm or the manifest's realm member sets it. Configure the realm lists every realm setting.

Plans and usage

Warm floor

The warm floor, warm_floor, is the number of an environment's copies the platform keeps running at all times. For production it is 0 on free and 1 on standard and pro. A development environment keeps one copy running on pro and none on the other plans. set_plan applies the floor, and read_status reports it. Plan and usage describes each plan's settings.

AI allowance

The AI allowance is the amount of AI model use a plan includes each month. An application uses it through the AI Allowance package, whose calls the egress gateway sends to the model provider on the platform's own key. Each call is counted in token units, a weighted count of its input and output tokens. read_usage reports the month's units as ai_allowance_units. Once the plan's quantity is used, calls are refused 429 allowance_exhausted until the next UTC month.

Credentials and sessions

Native client

A native client is a mobile or desktop app that signs its users in at an end-user realm's own authorization endpoint and calls the backend with the session token as a bearer token. It is declared on each realm of the application with configure_realm under its client_id and its redirect URIs, and its app signing identities where universal links, app links, or passkeys are wanted. It refreshes at the token endpoint with a rotating refresh credential, and it sends its version on every call.

Development build

A development build is a debug build of a native client, run in a simulator, an emulator, or on a phone. On one environment it uses the production hostname and signs in on the production realm, as the store build does. With development turned on, it uses the development hostname and the redirect scheme the development realm declares. Expo Go's own exp:// redirect is outside the redirect rule, so the sign-in is tested in a development build. A store build uses the production hostname and is declared on the production realm before it ships.

Credential

A credential is what a caller presents with a request: the browser's cookies, the tool's connection, a minted token, the application's platform credential, or an end-user session. What a caller may do depends on the credential, its scope, and its grants. Sign-in, sessions, and tokens compares every kind.

Platform credential

The platform credential is the credential the platform mints for one environment of an application and places in its container as TURNZERO_CLOUD_TOKEN. A running backend presents it to the platform's own services: storage, logging, the egress gateway, the push service's send route, and the accounts service's verification route. Each environment has one at a time, and every application has a development one for its local runs. Every deploy to production and every promote mints a new one for production, and rotate_secret on the development scope mints a new one for development.

Platform-minted credential

A platform-minted credential is one the platform mints for an environment. There are three: the platform credential, the database credential where the manifest declares the database kind, and the issue-tracking space's first token where it declares the issue-tracking kind. The platform stores them under the names credential-<application id>, database-<application id>, and issue-tracking-<application id>, and store_secret and delete_secret refuse all three. It returns the development platform and database values once, over the HTTP application programming interface (API) only, never the issue-tracking token, and never a production value.

Egress key

An egress key is the credential the platform creates for one declared upstream of one deployed copy and places in the setting the upstream's settings names as its key. An unchanged software development kit (SDK) presents it as a bearer token, and the gateway replaces it with your stored key. It works only on that upstream's route, and it lasts only as long as the copy, or until its upstream is ended. It is never returned to you. Call an external API with an API key shows it in use.

Minted token

A minted token is the credential for unattended work: a script, a pipeline, or a contractor's tool. mint_token limits it to the whole account or to one application, gives it only grants that the minting session had and asked for, and returns its value once. revoke_token ends it at any time. Minted tokens states how soon each service refuses a revoked token.

Account-scoped token

A minted token's scope, fixed at minting, is the whole account or one application. An account-scoped token, scope_kind account, can call actions across the account. It is refused where a call needs one application's credential, such as the logging routes or the platform's ai-allowance upstream. An application-scoped token works on its one application only, and cannot have the issues grant or a staff grant. Mint a token lists what each can call.

Bearer token

A bearer token is a credential presented in the Authorization header of an HTTP request. On the management HTTP API and the Model Context Protocol (MCP) endpoint, it is the tool connection's access token or a minted token. On the platform's own services, it can also be the application's platform credential.

Session

A session is the signed-in state one sign-in creates: the browser's cookies for the platform's site and, where an MCP client started the sign-in, that client's connection. The site's Sign out ends that browser's session alone. Sign out everywhere on the Sign-in & security page, or the sign_out_everywhere action, ends every session of the account at once, on every device. An end user's session belongs to the application's realm and is a separate thing.

Session token

A session token is the short-lived signed value that confirms an end user's session to your backend. It lasts one hour, and the platform renews it while the session lasts. Verifying an end user explains how your backend checks it.

Verification route

The verification route is the accounts service's POST /accounts/v0/verify, where a backend checks an end user's session under its platform credential. It is one of two ways to verify a session; the other checks the session token inside the process with the realm's public keys. A successful response gives the user, the realm, the verified addresses, the sign-in methods, the standing, and how long the result may be cached. The verification route describes the call.

Copy interval

The copy interval is how often each serving router picks up a realm's signing keys and revocation list: currently 30 seconds. A router that has not copied a realm's list in the last sixty seconds copies it before that realm's next request. So a session ended by a sign-out or a revocation reaches every router within sixty seconds. The router then sets the header x-turnzero-cloud-session to invalid on the session's requests, and refuses the session's token where an app presents it as a bearer. The platform can change the interval without any change to your application. Current values lists it.

Passkey ceremony

A passkey ceremony is the exchange in which a person's device creates a passkey for a realm or signs in with one. The accounts service runs it on the realm's own hostname, so the passkey works only there: the platform's own host for builders, and the environment's hostname for an application's end users. A native app can run it once the realm declares the app. Register a passkey from inside the app describes that case.

Stranded passkey

A stranded passkey is still listed on an account but cannot sign in on the hostname the sign-in page now uses. It was registered for a hostname the platform or an application no longer uses, such as an application's hostname before a rename, or before the platform recorded each passkey's hostname. read_account counts yours as stranded, apart from the held ones that work. You remove one of yours on the passkey page, /auth/passkeys, with no passkey prompt. Manage end users states how an end user removes one with POST /__account/passkeys/remove-stranded.

Custody

Custody is the platform's storage of secret values, which your project and conversations refer to by name. A secret stored for an application belongs to one environment, with no fallback to the other, and an account-wide secret is used for both. No management action returns a stored value. The egress gateway adds a stored credential to an outbound request itself and never gives it to your application, though an upstream that echoes it in its response sends it back. A value the manifest binds to a setting is the exception: the platform places it in the deployed copy.

Authority and approval

Management action

A management action is one entry of the platform's action catalog, such as deploy or read_status. An AI tool calls it as an MCP tool, a script calls it at https://turnzero.ai/api/v1/actions/<action_name> with a bearer token, and a signed-in page of the site calls the ones it uses. The action reference lists every action with its arguments and its refusals.

Management action tier

A management action tier is the category of a management action that sets whether it needs approval: observe, reversible, or destructive. An observe action reads state without changing it. A reversible action runs without a browser approval step. A destructive action runs only after a person approves it in the browser. Management action tiers and approvals explains the three.

Pending action

A pending action is the record of a destructive action's request while it waits for approval, runs, and reaches its outcome. Calling a destructive action creates the record and returns a description of the proposed changes with an approval link. A signed-in person approves or declines in the browser, and read_pending_action returns the state and the outcome.

Refusal

A refusal is the platform's response when it does not do what a request asked. It has a name such as environment_unavailable, an HTTP status such as 409, and a detail that gives the cause. The MCP tools and the HTTP endpoints name refusals the same way. Some management refusals include further members that state the cause as data, and the refusals reference lists them. A manifest that fails validation is refused with the JSON path of each problem in its violations member.

A refusal's detail, like the detail of any response, may end with a short code in parentheses, a rule code, which identifies the platform rule behind the response. You don't need it to act; quote it if you report a problem. Given a bare rule code as its query, read_documentation says it is a rule code and lists the pages that name it.

A refusal of a management action call the platform has accepted for handling also includes a reference: the short code the platform records the call under. Quote it when you report the refusal. A refusal returned before the platform accepts the call, such as one for a missing sign-in or a wrong method, has none. A refusal that includes a reference also includes help: the address of the refusal's row in the refusals reference. So do some refusals returned earlier, such as one for an unknown action or a wrong method.

Page address

A page address is the page member that some responses to a management action include: the address of the public page that explains the response, such as https://turnzero.ai/cloud/guides/plan-and-usage/. The response's detail says what happened and what to do next, and gives the title of a section of that page where one section applies. A pending action's response and a refusal include no page; a refusal includes help instead.

Your tool reads the page with read_documentation, passing the address as page unchanged. The action removes the platform's own address from the front, and the first part of the path that remains, such as /cloud/, identifies the documentation tree, so the call needs no tree. A search by query needs no tree either: without one, it searches every documentation tree your account can read.

Status

A status is the HTTP status code of a response. A deploy or a promote that passes its checks returns 202. Where the call included wait_seconds and the work ended within the wait, it returns 200. A refusal returns the code its definition gives, such as 403 or 409. An environment's condition, such as deployed, failed, or halted, is the state that list_applications and read_status both report.

read_status also reports compute_state, the hosting service's own word for the compute. Its top-level members describe the environment the call names in environment, production where it names none, and its top-level environment member names it. Read the status lists the values.

The platform processes

Control plane

The control plane is the platform's own running system, as distinct from the applications it hosts. It handles every management action, whether called as an MCP tool, on the management HTTP API, or from a signed-in page of the site. It records each action. The serving router and the egress proxy read an application's standing and declarations from it, and keep each response for a short, fixed time. Management action tiers and approvals states what the record contains.

Serving router

The serving router is the platform process that receives every request on an application's two hostnames. Where the manifest's audience requires an end-user session, it checks the session before it forwards the request. It forwards each request to the environment's compute with a mark the runtime harness checks. It also renews expired end-user session tokens and starts each scheduled run. read_logs with source: "router" reads its records, and Egress firewall and request limits states its time limit.

Runtime harness

The runtime harness is the code the platform loads into an application's process before the application's own server starts. It refuses a request from another machine that has no accepted router mark, sends the supported HTTP clients through the egress proxy, and records outbound connections under the log source harness. It also ends a request that runs past its deadline. It is the same in every environment. A local run loads none, and no part of it is offered for you to install. Node.js Runtime states each check and the settings that enable it.

Router mark

The router mark is a secret value the serving router adds, as a header, to each request it forwards to an environment's compute. The runtime harness refuses a request from another machine without it, 403 router_mark_required, and removes the mark before your code sees a request. So an application is reachable only through its managed hostnames. When the platform changes the mark, it re-creates each environment's running copy. The router mark states the check.

Scheduled run and due instant

A scheduled run is one request the serving router sends to a path a schedule declaration of the manifest gives, each time the declaration's cron expression, in UTC, makes a run due. The due instant is that time. The router sends it in the header x-turnzero-cloud-schedule-due. The run's key, the schedule's name with its due instant, lets a handler skip a run it already handled. Schedule describes the runs.

Log source and store source

A log source is the part of the platform that wrote a log record, which read_logs takes as source. Five are store sources, kept by the logging service: app, platform, router, egress, and harness. The container source instead reads the console of an environment's compute, its standard output and standard error. Choose the log source lists who writes each source.

Fallback output

The fallback output is where the Logging package's client writes the records the logging service did not accept: standard output by default. Those records are counted as dropped, and the counter logging.dropped shows the loss. Read logs and counters states the client's delivery limits.

Egress firewall and request limits

Egress firewall

The egress firewall is the control the platform applies to a deployed backend's outbound network access: the egress proxy, its declared hosts, and its observe and enforce modes.

Request limits

The request limits are the controls on a deployed backend's incoming requests: the time limit on each request, the per-address and per-user limits, and the check on the router mark. Egress firewall and request limits states each control and where its records are.

Execution window and grace interval

The execution window is how long one request to a deployed backend may run. An ordinary request has one length, and a scheduled run has another, the schedule execution window, which read_schedules reports. At the window's end the serving router responds 504 window_ended if no response header has gone out, and the request's request.signal is aborted.

The grace interval is the time the handler then has to stop. Past it, the runtime harness ends the process, with every other request it is handling. The settings HOSTING_WINDOW_REQUEST_SECONDS, HOSTING_WINDOW_SCHEDULE_SECONDS, and HOSTING_WINDOW_GRACE_SECONDS give the three lengths. The execution window states what happens to each request.

Egress

Egress is a backend's outbound network traffic to external services. It goes through the egress proxy in one of two ways. A tunnel reaches a host the manifest's egress list declares. The gateway calls a declared upstream and adds its stored credential. The platform's own endpoints are reached outside the proxy and need no entry.

HTTPS tunnel

The HTTPS tunnel is the egress proxy's route for a backend's ordinary HTTPS connections on port 443, such as the runtime's own fetch to an external host. It reaches the hosts the manifest's egress list declares, and in observe mode undeclared hosts too. It adds no credential. The HTTPS tunnel lists its checks.

Egress gateway

The egress gateway is the egress proxy's route for calls to a declared upstream. A backend calls /egress/v0/<upstream>/<path> on the platform's origin under its platform credential. The gateway adds the stored key from custody and forwards the call, so the application never receives the key. The platform's own upstreams, ai-allowance and issue-tracking, are reached the same way. The gateway states its rules.

Declared upstream

A declared upstream is an external API the application declares in its manifest's upstreams member or with declare_upstream: a name, a base URL, its key's custody name, and the key's header. A backend calls it at /egress/v0/<upstream>/<path> under its platform credential. The gateway adds the stored key before it forwards the call and never gives the key to the application; only an upstream that echoes the key in its response sends it back. Each declaration binds the upstream to one application. Its optional settings member lists the settings an unchanged SDK reads, and the key setting contains an egress key.

An upstream ends with undeclare_upstream, once the manifest no longer names it, or with its application or your account (End an upstream).

Call an external API with an API key states the declaration's members and the gateway's refusals.

Observe and enforce modes

Observe and enforce are the two modes of the egress proxy. In observe mode, the proxy records connection attempts and allows undeclared hosts that pass its other checks. In enforce mode, it refuses an undeclared host with egress_undeclared. A new application starts in observe mode, and platform staff switch it to enforce mode with set_egress_mode.

The database

Database and owner role

An environment's database and its owner role are the PostgreSQL database and the role that owns it, which the platform provisions for that one environment while the manifest declares the database kind. The development database and its owner role are provisioned at the first manifest submission that declares the database kind, on every application. The production database and its owner role are provisioned at the first deploy to production, or the first promote on two environments. On one environment, only local runs use the development database. Database describes both environments' databases.

Migration

A migration is one .sql file under the application's migrations/ folder, named with a zero-padded number that sets its order. The migration files define the application's whole schema. The platform provisions an empty database and creates no table. Never edit or rename an applied migration. Make a schema change as a new file.

Migration walk

The migration walk is the run of the Database package's migration function, applyMigrations, which applies the migration files when the application starts, before its server listens. The package's bootWalk starts it, and retries it every second for up to 120 seconds while the database connection is lost.

The walk applies each file the ledger does not list, each in its own database transaction, together with that file's ledger row. If a file fails, its transaction rolls back and the application does not serve. The same walk runs at a local start, at a deployed start in either environment, and when the test double is created.

Ledger

The ledger is the table schema_migrations, which the migration walk creates when it is absent. It records each applied file's name and the time it was applied. The next start skips every file the ledger lists, so a start after a failed file applies that file again.

Developer network rule

The developer network rule is the network access rule of the platform's database servers. A development server's public endpoint accepts a connection from any address, so a local run reaches the development database from any machine, with no address to register. The connection uses Transport Layer Security (TLS), and the database credential controls access. A production server accepts connections from the platform's own addresses and from no customer address. Add a database states what the rule means for a local run.

Storage

Storage area

A storage area is a named set of files the account declares with declare_storage_area or with PUT /storage/v0/areas/{area}. An area keeps one set of files per environment, so one file name can refer to a different file in each environment. An area is bound to one application and is deleted with it. undeclare_storage_area removes an area that contains no file and frees its name. Store files states the declaration's members and the file routes.

Acting identity

The acting identity is a string your application chooses to record who made a storage write. It is sent in the X-Acting-Identity header, separate from the credential. Every write needs one, and a write without it is refused 400 identity_required. It records who acted and grants no access. A transfer grant fixes it, so an upload under a grant sends no such header. Put, fetch, list, delete describes the header.

Transfer grant

A transfer grant is a short-lived credential a backend mints at POST /storage/v0/grants so a browser can upload or download one named file. An upload grant allows one write, and a download grant allows repeated reads until it expires. A grant expires five minutes after minting by default and works only for its file, direction, and route. While its application's owning account is suspended, the grant is refused account_suspended, and it works again on reinstatement within its expiry, or within its progress reads' window for a deploy's started upload grant. Store files states the grant's members and refusals.

Your AI tool gets an upload grant for a shell from the action mint_upload_grant, for an area of its own. It covers one file. A deploy's upload grant goes to the turnzero-cloud command alone: the call that prepares the upload returns it, and no response to your tool contains it. mint_upload_grant returns it as its own member, in the command's put line and that line's Windows form, and in two ready upload commands.

The grant fixes the environment and the acting identity, so no other header is sent, and no long-lived token reaches the shell. A deploy's upload grant accepts only the zip whose hash the preparing call named, and it also starts that zip's deploy, once.

An export's download grant is the one transfer grant for more than one file. The action mint_download_grant returns it for one completed export, inside the line that runs the turnzero-cloud command's export download, in that line's two forms. Until it expires, it reads, by name, that export's own files and the application's stored files in the exported environment that were created by the time the export listed them.

A file stored after the export, or deleted and stored again, returns no_such_file under that grant, as a name with no file does, and a new export includes it. The grant lists nothing and writes nothing, a read does not use it up, and every other route refuses it transfer_grant_not_admitted. Download the export describes the line.

A deploy's upload grant reaches one file of the application's deploy area, deploy-<application id>: one write, then one start of its deploy. After that start, it is valid for the command's own progress reads of that deploy, until five minutes after the deploy ends and never past fifteen minutes after the start. Your account's own credentials reach farther, but never there. Your tool's connection and a minted token reach the declared areas their scope allows, and on the deploy area each is refused area_scope_refused where the request names its environment.

Secret grant

A secret grant is a short-lived credential for one write of one secret, or for a local run's setup. A store_secret or rotate_secret call that gives no value returns it inside a command line, which runs the turnzero-cloud command on your machine. The grant works for that action, that name, and that scope, once, until the expiry the call returns. It works nowhere else: no other action accepts it as a credential, and most refuse the request secret_grant_not_admitted. While the owning account is suspended, the grant is refused account_suspended. Store a secret describes the line.

A store_secret call that gives no value and names generate returns no grant, because the platform creates the value itself.

A submit_manifest call that names local_run returns a secret grant inside the provision line. That grant works for two requests, each once: rotate_secret over the HTTP API for the application's development database credential, and for its development platform credential. The turnzero-cloud command describes the line.

Deploy area and export area

The deploy area, deploy-<application id>, is the storage area the platform creates and keeps for an application's deploy zips. Only a deploy's upload grant writes to it. It keeps one pending upload per environment: a zip no deploy has read yet, which the next upload prepared for that environment replaces. A zip is deleted once the deploy that read it ends.

The export area, export-<application id>, is the area request_export writes an application's exported database tables and export manifest into. The line that mint_download_grant returns downloads them. No area you declare may have a name that begins with deploy- or export-. Store files describes the deploy area, and Export or delete your account the export.

Issue tracking

Issue-tracking space

An issue-tracking space, also called an issue space, is the set of issue-tracking records one owner keeps: issues, the reports filed about them, checks, and ratings. Declaring the issue_tracking service gives an application one space, shared by both environments, and a manifest can instead bind it to a space of your account. Your account can have up to fifty spaces of its own. The space's credential stays with the platform. Issue Tracking describes the service.

Issue and report

An issue is the one curated record of a problem in an issue-tracking space, with a short identifier such as #12, a state, and an outcome. A report is one filing about an issue, in the words of the person, agent, or program that filed it, and is never edited. Several reports can belong to one issue. Feedback and ratings shows how to file one.

Grant level

A grant level is the set of issue-tracking calls the platform allows on a space: report files and reads reports, contribute also works on issues, and owner can make every call. A token with the issues grant has one, and an application's deployment reaches its own space at report, or a space of your account at the level the manifest gives. Grant levels are separate from the Issue Tracking package's four permission levels on a space's own tokens, file, work, record, and operator. A token for one issue space describes each level.

Monitored check

A monitored check is a test that a program runs repeatedly and records in an issue-tracking space under a stable key, passing and failing runs alike. An issue opens from the check only once its failures repeat. The platform's own test harness posts each run of its monitored checks into the platform's issue space. Issue Tracking lists the records a space keeps.

The library

Library

The library is the catalog of published entries the platform makes available: feature packages, vocabularies such as the style system, font families, and the requirements documents that define the package format. list_library lists the entries and read_library_entry reads an entry's files, and neither needs an account. A new publication replaces the published catalog, and your project keeps its own committed copy.

Feature package

A feature package is a library entry for a reusable capability. It contains the capability's product statement, detailed contract, and integration guide, and its compiled npm package where it has runtime code. A backend feature package describes a service the platform provides for each environment of an application, such as the database or the accounts service. A front-end feature package provides browser components and has no backend service.

Vocabulary

A vocabulary is a library entry of kind vocabulary: a set of documents that define a shared design language rather than a capability, such as the style system. Its entry contains its documents and, for the style system, its sheets and its resolver. A project keeps it under system/ui/<name>/. Use the library shows how to take one.

Closure and closure hash

A library entry's closure is every file the entry lists, each with its path. The closure hash is one hash over that whole closure, which list_library returns as closure_hash and your project records in system/manifest.json. A copy that changes or drops a listed file no longer matches its hash. Check the download uses it.

Public reads

The public reads are the four management actions that need no credential: list_library and read_library_entry, which read the library, and list_context and read_context, which read the published context. They still work while an account is suspended. A token with the issues grant can call them too.

Compatibility window

The compatibility window is the time the platform keeps an older version of the management contract, or of a backend package's contract, in service after a newer version replaces it. It lasts five years. A version replaced during the beta, before the first customer release, has no window.

Raise the minimum version says how to declare the lowest client version your backend accepts, which is how to refuse older installed native clients.

Test double

A test double is the module a backend package ships at its testing subpath, @turnzero/<name>/testing. In your application's own tests, it takes the place of the service or connection behind the package's client. The database double is a PostgreSQL engine inside the test process, with your migration files applied. The other doubles run in memory, inside the test process, and return their services' responses and refusals. A double runs in tests only, so your tests need no account, no connection, and no environment file. Test your application locally lists each double.

Held copy and vendored copy

A held copy, also called a vendored copy, is your project's own committed copy of the library entries it uses. It sits in the project's system/ folder and is recorded in system/manifest.json. A newer library publication does not change it. The application installs a package's compiled code from a second copy under app/lib/<name>/, declared as a file: dependency. Use the library states each step.

Instance file

An instance file is the record a Turn Zero Blueprint project keeps for each feature package it uses, under requirements/app_features/. It pins the package's version, and a project that uses an upstream through the Egress package records the upstream and its credential's name there. A project without Turn Zero Blueprint has no instance file, and system/manifest.json records the version. Use the library says when to update it.

The connected tool

Skill

A skill is a ready procedure the server offers as an MCP prompt, which a client that supports prompts may show as a slash command. The server offers a skill only when every action it uses is available. A client that lists no prompts reads the same instructions with read_context, id skill:<name>, such as skill:deploy. deploy, release, and diagnose are three of the current skills.

A skill's text lists its numbered rules. Where a skill offers a short path for the common case, the path comes before the rules. Each step lists the rules it follows, and the path says which rules apply only when a condition is met.

A short skill is one page. A long skill is returned in pages, each small enough for one read_context call with limit set to 16000. Its first page contains the short path, the rules every application follows, and a few rules that say on their own line when they apply. It lists the other pages by id, such as skill:deploy:database. Each of those contains the rules for one case, under their numbers in the whole list, or the reasons behind the rules; a skill with no case page has the reasons page alone. The prompt includes the first page.

Resource

A resource is readable context your tool loads before it starts work: the overview, the service contracts, the manifest schema, and the authoring bundle that packages them. Each is named in the form context://manifest_schema. A signed-in tool can also read each documentation tree whole as a resource. A tools-only client reads the same content through list_context and read_context.

Documentation tree

A documentation tree is one of the platform's sets of published documentation pages, each under its own path, such as /cloud/ for this documentation. read_documentation returns one page of a tree or searches the trees, and a signed-in tool can read a tree whole as a resource. Your account reads only the trees it has access to. Page address says how a tool reads a page a response gives.

Related

• What Turn Zero Cloud is — what the platform provides and where it stops.
• Applications and environments — the application record, its environments, the version history, and the halted state.
• Management action tiers and approvals — the three tiers, the pending action, and the credentials.
• Sign-in, sessions, and tokens — every credential, how long it lives, and what ends it.
• What happens without asking — which actions complete on your request alone and which ask first.
• Action reference — every management action's payload, tier, and refusals.