Author the manifest #

View this page as Markdown

On this page

Declare the services and settings your app needs in its manifest, the configuration you submit to Turn Zero Cloud. Read this page before the first deploy, when adding a service, or when a manifest submission is rejected.

Prompt:

Get this app ready to deploy. It has a database, users sign in, it calls Stripe, and anyone can use it.

Also works:

  • "Let users upload their receipts."
  • "Run the daily report every morning at 6am UTC, and show me how to tell whether it ran."

The manifest declares your application's services, allowed outbound hosts, and audience. A server also declares its health path. For static files alone, follow Publish a static site; that route needs no health path or start command. In a local project, your AI tool keeps it in manifest.json and submits it with submit_manifest. In an AI chat without a project folder, submit the manifest directly; see Deploy from a chat.

Read What you need and Before your AI starts, then follow Steps to write and submit the manifest. The steps also cover health paths, stored settings, WebSockets and scheduled work. Expected result explains the response; Refusals gives the remedies.

What your AI tool does #

  • Reads the manifest-author skill (read_context, id skill:manifest-author) and follows it, with the schedule skill for scheduled work and the add-service skill for a service added later.
  • Reads the manifest schema, published as the context://manifest_schema resource. Without that connection, it reads the same file at https://turnzero.ai/cloud/reference/sources/schemas/manifest.schema.json.
  • In a local project, writes the packages member from the project's system/manifest.json, as Use the library describes.
  • In a local project, keeps the manifest as manifest.json, and submits it again after each edit, except an edit to its application member alone, which declares nothing.
  • To preview an edit, calls check_manifest with the whole manifest. It changes nothing and lists the paths added, removed, and changed. Unlike a submission, this check returns no next calls or settings rows.
  • Asks you what the application uses before it writes the manifest, and asks for no browser approval.

What you need #

  • A description, in your own words, of what your application uses: which managed services, the outside services it calls, and who is allowed to use it. For a server, include its health check address.

Before your AI starts #

For the AI tool: Check the following before starting.

  • A connected, signed-in AI tool (Connect your AI assistant).
  • The application's identifier from list_applications. A new application is created with create_application, as step 1 (Create the application) of Deploy from your computer describes.
  • For scheduled work, the common limits: 25 schedules at least one minute apart. read_plan_quotas returns them for either size.

Steps #

For a refused submission, see Refusals. For a failed deployment, see Deploys.

Add the service a feature needs and resubmit the whole manifest. The manifest explains each field. For a server, the manifest sets neither a start command nor a port: the image build installs runtime dependencies when present, npm start runs the server, and the server listens on PORT.

A server application runs on Node.js 24; the platform ignores engines in package.json. The manifest accepts no name, runtime or start field. The install command is npm install --omit=dev.

Without a start script in the root package.json, npm uses the root server.js. The platform sets PORT=8080, and PORT is reserved. What a deployed application needs describes these requirements together.

A manifest that works #

This manifest declares a database and sign-in, the health path, one outside host, an audience open to everyone, two library packages, and a stored value bound to a setting.

{
  "manifest_version": 1,
  "services": [
    { "kind": "database" },
    { "kind": "accounts" }
  ],
  "health": "/health",
  "region": "usa",
  "egress": ["api.stripe.com"],
  "audience": { "kind": "public" },
  "packages": [
    { "name": "database", "version": "0.15.0" },
    { "name": "account", "version": "0.23.3" }
  ],
  "settings": {
    "STRIPE_WEBHOOK_SECRET": { "secret": "stripe-webhook-secret" }
  }
}

For a server that needs no managed services, outside hosts or library packages, this is a complete manifest:

{
  "manifest_version": 1,
  "services": [],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": []
}

This complete manifest declares a database with no library package; connect with a PostgreSQL driver.

{
  "manifest_version": 1,
  "services": [
    { "kind": "database" }
  ],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": []
}

This complete manifest declares a database, an invited audience with sign-in by email code, and the non-secret setting SITE_TITLE as a plain value. Invite each person as Make sign-up invitation-only describes.

{
  "manifest_version": 1,
  "services": [
    { "kind": "database" },
    { "kind": "accounts" }
  ],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "invited" },
  "realm": { "sign_in_methods": ["email"] },
  "packages": [],
  "settings": {
    "SITE_TITLE": { "value": "Team notes" }
  }
}

The server must still answer at /health, as Choosing the health path explains.

Your AI tool submits the chosen manifest with submit_manifest, giving the application's identifier as application and this object as manifest. Each submission records the whole manifest, so your AI tool always sends all of it. The platform reads no file on your computer, so the call carries the manifest itself. Expected result describes the response.

A deploy runs under the manifest submit_manifest recorded. The project's manifest.json goes into the artifact the deploy uploads. The copy in the artifact is optional: the deploy compares it with the recorded manifest and never uses it. Where the two differ, the deploy returns manifest_notice and refuses nothing. The optional application member, the lowercase UUID of the application the folder deploys to, declares nothing: the platform checks its form alone, and the comparison leaves it out on both sides.

submit_manifest, deploy, and run_schedule are reversible-tier actions, so none needs your approval in the browser. deploy and run_schedule start work that finishes in the background. With wait_seconds, each response waits until that work ends, for at most 45 seconds; otherwise the tool reads the outcome with read_status and read_schedules.

In a local project, your AI tool writes the packages member from system/manifest.json at each submission; Use the library describes the copy and shows a row beside its entry. The platform keeps the member as you submit it and never reads system/manifest.json, so a list written by hand stands until your AI tool's next copy replaces it; keep none by hand. Without a folder manifest, your AI tool enters the names and versions from read_library with no entry instead, as Use the library describes.

The required packages member lists copied library packages, not the services the application calls. An application using the storage HTTP routes without the Storage package lists no Storage row; with no library packages, it declares "packages": [].

Resolve a package notice #

Each deploy compares the list with the package copies under the zip's lib/. Its manifest_notice lists each copy whose turnzero.entry and version the list does not contain, and each copy it left unread or could not compare (What the deploy zip holds). A package.json object with no turnzero, or with a turnzero object that has no entry, such as your own package's, triggers no notice.

Where the zip's manifest matches the recorded one and every package copy can be read, compared, and paired with its recorded row, the deploy returns no manifest_notice.

When the notice names a copy absent from packages, your AI tool checks whether the application still uses it. A direct HTTP call to the platform's AI Allowance route uses no package copy, so removing the copy does not remove that route.

The package's Lifecycle, Migration, and Removal section is in features/<name>/<name>.md, under the project's library folder (normally system/). Before deleting that folder, read any removal directions in the prose before the section's first Migration entry. Read its Migration entries when changing versions. Without a library folder, read the document through read_library with entry and file (Read what is published).

For a copy the application still uses, your AI tool compares the copy's version with its row in system/manifest.json. If the versions differ, it gets the entry's library take command from read_library and runs it again (Use the library, step 3: Add an entry to the library folder). It then writes packages from system/manifest.json, calls submit_manifest, and deploys again.

Without a folder manifest, your AI tool corrects packages using the names and versions from read_library, then submits the manifest and deploys again.

For a package the application no longer uses, your AI tool removes its lib/<name>/ folder, its file: dependency from package.json, and any imports of it. Where the project has a library folder, it also removes the entry's system/features/<name>/ folder and its row in system/manifest.json together. It then rewrites packages from the remaining rows. Without a folder manifest, it removes the package's row from packages directly.

Removing the copy changes no other manifest member or platform resource. Follow any removal directions in the prose before that section's first Migration entry for the services, upstreams, or egress declarations it needed. Keep those another part of the application still uses.

After removing a package from a local project, your AI tool runs npm install in the application folder to refresh package-lock.json and node_modules. If it fails, correct the cause its error names and run it again before submitting. In Windows PowerShell, run npm as What your computer needs describes.

Once the install succeeds, it calls submit_manifest with the corrected manifest. A notice belongs to the deploy that returned it. The correction may be submitted while it runs and changes no deploy already started. That deploy uses the package copy in its zip under the previously recorded manifest. Follow the package's Migration entry for any step the version change needs.

Wait for that deploy to end through read_status with wait_seconds before deploying the correction. A new deploy counts toward the daily quota. A refusal adds no version. Repeating the same accepted deploy while it is in flight can return that run. After it ends, a fresh accepted deploy creates a new version, even from the same zip (Checks before a deploy).

turnzero library take updates packages in the application manifest after each download. If no manifest exists, it creates one in the application folder. Where that member differs from the recorded manifest, a zip carrying it also draws a manifest_notice naming packages. Submit the updated manifest before deploying.

The manifest declares no environments. A new application has one, production, and create_environment adds development (Test in development, then promote). A manifest with an environments member is refused environment_unsupported.

Paths that begin with /__account/ or /__router/ belong to the platform on every application address, so build no routes under them. The platform reads a request's path as your code might, with its escapes decoded, its .. segments resolved, and its letter case ignored. So a request naming either prefix in another form never reaches your application. A manifest that names such a path, as a scheduled job's handler, the health path, or a path open without sign-in, is refused.

Reading a refusal #

A refusal before the manifest is recorded changes nothing. A validation refusal, manifest_invalid, lists the JSON paths to correct in its violations member, such as /egress/3 for a malformed hostname. Your AI tool corrects each path and submits the whole manifest again.

The platform checks each service entry and the audience against the rules for its kind. It reports only those rules' violations. For example, a schedule named Hourly Tick is refused with one line, at /services/0/schedules/0/name, giving the naming rule. Where no kind matches, one line at its kind path lists the available kinds.

An entry of the audience's session_free_paths, or of upstreams, that breaks a rule is refused at its own path, such as /audience/session_free_paths/0 or /upstreams/openai/base_url. The line names the rule, or for an upstream the refusal declare_outbound_api would give, such as refused_platform_host. Every entry's line comes in the same response, and nothing is recorded.

Some refusals give a cause instead of a path, before anything is provisioned: region_unavailable, declared_tenant_contradicts_route, declared_audience_contradicts_route, and the refusals of a binding in settings. The one region available is usa. The schema also lists europe, uk, and global, and a submission naming one is refused region_unavailable.

Some refusals come after the manifest is recorded, such as database_provisioning_failed when the database setup did not finish. The response says the manifest is recorded, and its detail lists what was set up and what was not. Read it, then submit again to complete the setup. A submission is safe to repeat, after a partial failure among other cases: it records the manifest again, confirms what stands, and mints nothing it already minted.

The guide for each part of the manifest #

Each part of the manifest below has a guide for its task, which shows that part in use. The manifest schema's reference page gives the rules for each.

In the manifest Guide for the task
The database service Add a database
The accounts service, with audience and realm Add sign-in to your app
The object_storage service Store files
The push service Send push notifications
The schedule service Add a scheduled job, and Run scheduled work below
The issue_tracking service Issue Tracking
The health path Choosing the health path below
The smoke_paths member Listing smoke paths below
The egress list Writing the egress list below
The settings member Bind a stored value to a setting and Set a value that is not secret below
The upstreams member Call an external API with an API key
The websockets member Use WebSockets
The packages member Use the library
The AI allowance needs no member of its own, egress entry or upstream. Its package needs a packages entry; a direct call needs none. Call an AI model
The application member The members of the manifest concept page

Choosing the health path #

An application whose zip declares its own start must declare health. That means a root package.json with scripts.start, or a root server.js. Without health, a deploy, promote, rollback or redeploy is refused 400 health_path_undeclared. If either environment has a server, running or halted, or a server application's deploy, promote or redeploy is in flight, submit_manifest and check_manifest refuse a manifest without health the same way. No version is recorded, no deploy is counted, and no build or compute act runs.

The health path is an absolute path on the application's own address, conventionally /health, and never a full URL. At each deploy and promote, the platform requests it every three seconds until it returns status 200 exactly three times in a row, for up to 180 seconds, and follows no redirect. A 503 or a connection error between them starts the count again. The deploy health check describes the probes, when the check ends early, and the evidence a failed check keeps.

The check reads only the status code. The body can hold APP_VERSION, other fields, or nothing. Where the check fails, the deploy's record keeps the first 512 bytes of the last non-200 body as evidence.

The path in the manifest must be the path your server routes, character for character. /health and /healthz are two different paths, and a server that routes one fails the check for the other.

Serve the path from the backend's own server, from the moment the server listens. Return 503 until the application can take requests, never a 4xx, then 200. A route mounted late then never ends the check early, because a 503 never counts toward it. A server with a database waits to listen until its migrations finish, so a failed migration ends the process before it serves: until it listens, the check treats it as starting and keeps waiting.

For an environment that runs no version yet, the platform refuses the deploy health_path_unserved before anything is built, where no source file of the zip names the path's last segment. The turnzero command makes that reading before its upload: it prints the same refusal and ends with status 3, with nothing uploaded. For an environment that already runs a version, the command only warns.

The segment counts with its slash, as in '/health', or bare inside quotes, as in @Controller('health'). A file whose own path holds it, such as routes/health.js, counts too. package.json and the lock files never count. Documentation counts only where its own path ends with the whole health path, such as public/health.txt for /health.txt. Any source file that names the path passes, a comment included.

Under an invited or workforce audience, the platform's own check still reaches the health path. It calls your application from inside the platform and never passes through the sign-in check. A request to the health path from outside, without a session, is treated like a request to any other path. It is refused 401 authentication_required, or sent to the sign-in page in a browser.

To open the health path to everyone, list it in the audience's session_free_paths. Anyone can then read whatever the path returns, so return nothing there you would not publish. Two limits apply to the list: / alone is refused, and a listed path also opens every path below it. Make sign-up invitation-only, step 1 (Choose who may sign up) gives the list's other rules.

Where the manifest declares health, the health member of submit_manifest's response says whether the path is gated: its gated is true where a request from outside without a session is refused. It is not the deploy's own check, the health_gate step read_status shows, which calls the path from inside the platform whatever gated says.

Listing smoke paths #

smoke_paths is an optional list of routes to check before a deploy or promote sends traffic to the new version. Use it for important GET routes that read data without changing it, for example "smoke_paths": ["/api/items", "/account"]. After the health check passes, the platform requests each listed path in order. Leave it out to check only the health path.

Each entry is a path written like the health path: it starts with /, holds no space, and is never a full URL. The list holds one to five different paths. A path under /__account/ or /__router/ is refused, because those prefixes belong to the platform.

Smoke checks share one 30-second deadline across all listed paths. A probe fails on 404, a status of 500 or above, or no response; other statuses, including redirects, 400, and 401, pass. Failed probes are retried every three seconds while time remains.

Choose the routes whose crash should stop a deploy or a promote before it switches:

  • List only routes that answer GET. A route with no GET handler often answers 404, which fails the check.
  • List only routes that change nothing on GET. On a promote they run against production's data and secrets.
  • List routes that begin their response within ten seconds.

The smoke requests reach the new copy directly, as the health check's do, so an invited or workforce audience needs no session_free_paths entry for them. A rollback, a restart, and a promote of the version production already serves request no smoke path. Checking your other routes describes the check and the evidence a failed one keeps.

Where a deploy fails with smoke_path_failed, fix the route and deploy again. Or remove the path from smoke_paths and submit the manifest again.

Writing the egress list #

List every host the backend calls on the open network. Write each as an exact lowercase hostname, or as a host family with one leading wildcard label. *.example.com covers every name below example.com at any depth, but not example.com itself; list that separately if the backend calls it.

Write no scheme, port, path, or IP address: the tunnel reaches port 443 only (Egress firewall and request limits). For an API's stored key, use a declared upstream by default. The gateway connects to that host, so it needs no entry in egress.

For a client whose host is fixed in code the task forbids changing, bind its key and list that host in egress. Follow the binding exception. If an entry admits a declared upstream's host, tzcloud_submit_manifest names it in egress_notice. The platform's own endpoints need no entry: the database and storage the manifest's services provision, and the platform's origin, which serves the egress gateway, sign-in verification, and the actions available to the platform credential.

While the application is in observe mode, read_logs with source: "egress" and filter: "undeclared" shows the hosts it reached that the list does not include. Add the ones that belong before platform staff move the application to enforce mode.

Bind a stored value to a setting #

Your code reads some stored values directly, such as the sample's Stripe webhook signing secret. The optional settings member binds each one to a setting. Each key is the setting name, and secret is the name the value is stored under. settings has at most fifty entries. A value that is not secret takes the value form instead, as Set a value that is not secret describes.

Store the value with store_secret under the same name, at each environment's scope of the application, as Store a secret describes. Each deploy and promote reads the value stored for its environment and sets it in the container. A replaced value takes effect at the environment's next deploy or promote, or at a restart_application where the running copy already has the binding. Replace a value gives a replacement's steps and how to check that it reached the running copy.

The sample's binding has three parts, the same example Store a secret follows. First your AI tool stores the secret: it calls store_secret with these members and runs the command the call returns.

{
  "name": "stripe-webhook-secret",
  "application": "<application id>",
  "environment": "production",
  "value_file": "../secrets/stripe-webhook-secret.txt"
}

Then the manifest's settings binds the stored name to the setting, as the sample above does.

"settings": {
  "STRIPE_WEBHOOK_SECRET": { "secret": "stripe-webhook-secret" }
}

From the next deploy, the code reads the value from its setting.

const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;

The submission's settings rows say, per setting and environment the application has, whether the name is stored there yet. A deploy or promote is refused setting_secret_missing while its environment's value is missing.

A setting name is an upper-case letter, then upper-case letters, digits, or underscores, ending in a letter or a digit, at most 64 characters. A name the platform reserves is refused manifest_invalid at the setting's own path. That covers any name under TURNZERO_, APP_, HOSTING_, EGRESS_, ROUTER_, NODE_, or NPM_, and PORT, PATH, HOME, HTTPS_PROXY, HTTP_PROXY, and NO_PROXY.

Some stored names are never bound, and the Refusals table gives each cause:

  • a name at account scope or at another application's scope;
  • a name the platform created, such as the platform credential;
  • an upstream's key, which the gateway applies and never gives to the application;
  • a sign-in method's or a push provider's credential.

The same rule applies when configuring a credential. configure_app_sign_in and configure_push refuse a stored name bound to a setting, with name_bound_to_setting. declare_outbound_api refuses it with upstream_key_is_bound. A binding counts while the manifest's settings names it, and while a running copy has it, until that environment's next deploy or promote of a manifest without it. A deploy, promote, or redeploy in flight that recorded it counts too, until it ends.

A local run gets no bound value, because no call returns a stored value: the provision command writes the platform's own settings alone. Give a bound setting a local value on a line of your own in .env, or in your shell.

For an outbound API key, use a declared upstream by default. The gateway keeps the key out of the container, and a replacement needs no redeploy. Bind the key only for the fixed-host exception.

Set a value that is not secret #

A setting your code reads that is not secret, such as a page title or a feature flag, goes in settings as {"value": "<text>"}. Each deploy and promote sets the value in the container as a plain setting. The value is the same in every environment.

"settings": {
  "SITE_TITLE": { "value": "Receipts" }
}

The code reads it from its setting, process.env.SITE_TITLE, as it reads a bound one.

Each entry of settings holds exactly one of secret and value. A value is text of at most 4,096 characters, and it may be empty. It holds no line break and no other control character: a value of several lines, such as a key or a certificate, is a secret. An entry that is not exactly one of the two forms, or whose value breaks these bounds, is refused manifest_invalid at its own path, such as /settings/SITE_TITLE. Its violation names both forms and never repeats the value.

The setting name follows a binding's rules above, and it may not be a name an upstream's sdk_settings sets. A name that breaks either rule is also refused manifest_invalid at its own path.

Never put a secret in value. The recorded manifest and the record of each version that applied the value keep it as written, so a credential put there stays on those records after the manifest is corrected. Store a secret with store_secret and bind its name, as Bind a stored value to a setting describes. If a credential was put in value, store it under a name, bind that name, and replace the credential with its provider.

To use different values in development and production, store each environment's value under the same name at its own application scope. Bind that name even if the value is not secret. Your code can also choose a value by APP_ENVIRONMENT.

A changed plain value takes effect at that environment's next deploy or promote. A restart reapplies the running version's recorded value. A rollback reapplies the value the selected version last used in production. If production never ran that version, the rollback uses the value recorded by its deploy.

Until the next deploy or promote, read_status lists the changed setting by name alone in that environment's bound_not_applied. The submission's settings rows omit plain settings because no stored value is read for them.

turnzero provision writes no line for a plain setting. For a local run, copy the value from the manifest into .env (Run your app on your computer).

Declare an upstream in the manifest #

An upstream is an outside API your backend calls through the platform's gateway, which adds the stored key on the way. The optional upstreams member declares each one in the manifest. Each key is the upstream's name, and each entry takes the members declare_outbound_api takes except application. Call an external API with an API key gives the task, the entry's rules, and the call through the gateway.

{
  "manifest_version": 1,
  "services": [],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": [],
  "upstreams": {
    "openai": {
      "base_url": "https://api.openai.com",
      "credential_name": "openai-key",
      "auth_header": "Authorization",
      "auth_format": "Bearer {value}",
      "sdk_settings": { "base_url": "OPENAI_BASE_URL", "key": "OPENAI_API_KEY", "base_path": "/v1" }
    }
  }
}

An upstream's sdk_settings is not the manifest's top-level settings: settings gives your code its own values, and sdk_settings gives an unchanged SDK the gateway's address and, with a key, an egress key.

Each submission declares every entry, as declare_outbound_api would. Each deploy and promote sets the entry's sdk_settings in the new copy. Keep sdk_settings.key where running copies have that setting. Omitting it, or sdk_settings entirely, revokes those copies' egress keys in both environments; the submission reports this.

The stored upstream credential can be missing at submission. The deploy still succeeds, but its outcome.credentials_missing lists the upstream. The gateway refuses calls to that upstream until store_secret stores the credential.

While upstreams names an upstream, declare_outbound_api refuses to change it, manifest_owned_field; change the entry and submit again instead.

A submission never removes an upstream's declaration, so a running version can keep calling it. To remove the declaration, first remove its entry from the manifest and submit it. Then deploy and promote the version that no longer calls the upstream. Call declare_outbound_api with its name and remove: true. This call is refused manifest_owned_field while the manifest still names it.

While the platform's store answers, its calls are refused in both environments within about 30 seconds by default. During a store outage, a gateway may keep using its cached declaration for up to an hour (End an upstream).

Configure sign-in and push in the manifest #

The optional realm member sets up sign-in for every end-user realm the application has at once. It takes the members of configure_app_sign_in that are the same in every environment: sign_in_methods, creation, entra, and apple. It also takes clients, the native apps that sign in, with one list for each environment.

While the recorded manifest lists an environment's clients, change that list in the manifest. configure_app_sign_in can change only each listed client's minimum_version and update_url. It refuses manifest_owned_field for a call that adds or removes a client, or changes any other client field. The manifest's services must include the accounts kind.

A sign_in_methods list with passkey lists email beside it, as in the sample below; otherwise submit_manifest refuses it manifest_invalid with passkey_not_sole_route. Configure the realm lists which realm fields the manifest owns and which stay with configure_app_sign_in. For one company's staff, Allow only one company's staff declares the workforce audience beside the entra route.

A push entry in services may also name its providers, apns and fcm, with the members configure_push takes. Apple's environment is left out, because the gateway differs by environment. Development uses sandbox and production uses production until configure_push sets another.

{
  "manifest_version": 1,
  "services": [
    { "kind": "accounts" },
    {
      "kind": "push",
      "apns": { "team_id": "ABCDE12345", "key_id": "KEYID12345", "bundle_id": "com.example.app", "key_secret_name": "apns-key" },
      "fcm": { "project_id": "example-app-12345", "service_account_secret_name": "fcm-service-account" }
    }
  ],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": [],
  "realm": {
    "sign_in_methods": ["google", "apple", "email", "passkey"],
    "creation": "open",
    "apple": { "services_id": "com.example.app.signin", "team_id": "ABCDE12345", "key_id": "SIGNKEY123", "key_secret_name": "apple-signin-key" },
    "clients": {
      "production": [
        { "client_id": "com.example.app", "redirect_uris": ["com.example.app:/callback"] }
      ]
    }
  }
}

Each submission applies these members to each environment the application has, from that moment, as the two actions would. On an application with one environment, that is production alone, and create_environment applies them to development when it adds it. So re-creating the application, or copying it into another account, takes this manifest, a store_secret for each credential, and a deploy. Each credential member names a stored secret, never its value.

The clients lists are the exception: each goes to its own environment's realm alone. A development list on an application with one environment is checked at each submission, and create_environment declares it. A re-created or copied application has new hostnames, so its https redirect URIs name them. Otherwise the submission is refused whole, recording nothing. Each client's minimum_version and update_url stay with configure_app_sign_in (Sign in from a native app).

A credential not stored yet is accepted. The submission's detail names each credential not stored yet, with the environment where only one environment lacks it, and the detail of create_environment names each one development lacks. A deploy still succeeds, and its version's outcome.provider_credentials_missing lists each credential its environment cannot use yet. A sign-in credential stored after a submission is used once you submit the manifest again.

While the manifest names a push provider's field, configure_push refuses to change it, manifest_owned_field, and the detail names each field. Change the manifest and resubmit instead. Apple's gateway stays with configure_push, because it differs by environment.

A submission refused after recording the manifest lists in its detail the realms or push configurations it set up and those it did not. Make any correction detail asks for and submit again to finish setup.

If create_environment is refused while configuring development, its detail describes the sign-in or push member it reached. It says whether that configuration was recorded or a credential was taken back. Follow its remedy: repeat create_environment or correct and resubmit the manifest (Refusals).

Accept WebSocket connections #

For a server, the optional websockets member declares that it accepts WebSocket upgrades. A serverless application's manifest refuses this member with serverless_no_websocket. Without it, every upgrade is refused websockets_not_declared. The empty object admits a page on the application's own hostname and a client outside a browser, and origins lists up to ten other browser origins whose pages may connect. Use WebSockets gives the member's rules, the server and client code, and the connection limits.

Adding a service later #

The add-service skill adds the entry to services and submits the whole manifest again. The next deploy sets the settings the new service adds in the environment it reaches, such as the database connection string or the realm's public keys. On the manifest concept page, The members lists each kind and What submitting does what a submission provisions, and The guide for each part of the manifest links the guide for each kind.

For the prompt "Let users upload their receipts", add this entry to services:

{ "kind": "object_storage", "areas": [{ "name": "receipts", "account_keyed": true }] }

A manifest can contain only one object_storage entry. Its optional areas list holds 1 to 50 areas, with each name listed once. Each area has exactly two fields: name and the boolean account_keyed.

An area's name starts with a letter or digit, followed by letters, digits, underscores or hyphens, up to 64 characters in total. It matches ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$. Names beginning export- or deploy- are reserved for the platform. So is images- followed by an application's UUID; other names beginning images-, such as images-thumbs, are not reserved.

account_keyed is required for each area and has no default. Use true for files that belong to individual end users, and prefix each file name with that user's ID. Use false for files the whole application shares.

The platform records this value and returns it in list_storage_areas. It does not separate files by end user; your backend must check which files each caller may read or change.

account_keyed cannot change for an existing area; use a new area for a different value. Before the manifest is recorded, a conflict is reported as manifest_invalid, with differing_redeclaration in violations. A conflict that appears after that check returns 409 differing_redeclaration, and the manifest stays recorded.

The submission declares each listed area and provisions nothing. Your AI tool writes the upload route. You can also omit areas and use the bare entry {"kind":"object_storage"}. Declare an area before using it, through the manifest, declare_storage_area or the application itself. Storage routes work for a declared area with or without this entry; Store files shows the declaration and access checks.

The schema also accepts email and custom_domain. Declaring email provisions nothing, and a custom_domain entry declares the application's own domain for production (Attach your own domain). A manifest declares one custom domain, so a second custom_domain entry is refused manifest_invalid at its path. Email send is available to every application.

Removing a database or accounts entry deletes neither the database nor the end-user realm (Changing the manifest). Removing a schedule stops its future runs, and its run records are kept for the run-history retention period.

Bind a space to some of its components #

An issue_tracking entry that names a space your account owns binds the application to that space (Keep your own issue list). If its level is report, the entry may also name components, one to two hundred of the space's declared component names, each once and at most 64 characters. A name the space does not declare is refused invalid_request; the issue binding and its token stay as they were. The manifest is recorded and the other kinds are set up. Submit the manifest with the name corrected to bind the space.

{ "kind": "issue_tracking", "space": "7d3f1c2a-9b4e-4f61-8a27-5c0e2d9b1f44", "level": "report", "components": ["billing", "sign-in"] }

The platform then mints a report token for the binding, limited to that list, and the application's calls reach the space under it instead of the space's own token. Such a binding files reports in the listed components and reads the issues they hold, sees no restricted issue, and takes the /v2 calls submit, read, list, and search alone. Every other call, and every /v1 call, is refused issue_tracking_call_refused.

A submission that changes the list or the level mints a new token first, then revokes the old one. If the new token cannot be minted, the old binding and its token stay as they were. Moving the binding to another space, deleting the development environment it alone serves, deleting the application, deleting the account, or deleting the space with tztrack_delete_space revokes the token. A later submission naming no space keeps the binding and its token. After the space is deleted, remove space from the entry before the next deploy (Delete a space).

components requires a space. With a component list, level must be report or left out to use that default. Any other level is refused level_invalid. Only the owning account can bind the platform's own issue space, at report with a component list.

Run scheduled work #

To add a job to an application you already have, step by step, read Add a scheduled job. This section describes the schedule declaration and when it starts. The Schedule handler reference gives the request headers, status-code rules, and private-path check together.

Declare the schedules #

For the prompt "Run the daily report every morning at 6am UTC, and show me how to tell whether it ran", your AI tool adds a schedule service entry. Each schedule has:

  • a unique name of at most 64 characters matching ^[a-z][a-z0-9_]*$, so hourly_heartbeat passes and hourly-heartbeat is refused manifest_invalid. A schedule's name is an identifier in the manifest and its records, so it takes underscores and no hyphens. An application's name, which matches ^[a-z][a-z0-9-]{0,39}$, takes hyphens and no underscores, since it becomes part of hostnames, which hold no underscore;
  • a five-field cron expression in UTC: minute, hour, day of month, month, and day of week, so 0 6 * * * means 06:00 UTC every day;
  • an absolute handler path.

In the entry, schedules lists them, each with name, cron, and path, the handler path. The sample below declares the prompt's daily report beside the Schedule package's row. That row is optional. A handler written without the package, as A handler without the package shows, needs no row, so packages lists only the project's other library entries, and is [] where it holds none.

{
  "manifest_version": 1,
  "services": [
    {
      "kind": "schedule",
      "schedules": [
        { "name": "daily_report", "cron": "0 6 * * *", "path": "/jobs/daily-report" }
      ]
    }
  ],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": [
    { "name": "schedule", "version": "0.3.3" }
  ]
}

Check cron and schedule limits #

The expression accepts numbers, ranges, lists, steps, and *. Month names, day names, macros, and a seconds field are not accepted. When both day fields are restricted, a date matching either one is eligible. An expression with no due time in the next year is refused.

Before the first submission, read the schedule limits with read_plan_quotas: schedule-minimum-interval is one minute and schedule-count-limit is 25 for either size. Choose a frequency within both. The platform checks them at submission and at a size change:

  • A schedule whose due times fall closer together than the minimum interval is refused schedule_interval_below_plan: its interval is below the one-minute floor. The interval applies in both environments.
  • More schedules than the count limit are refused schedule_count_over_plan.
  • A size change whose target limits the current schedules exceed is refused plan_schedule_conflict.

One schedule entry contains up to 25 schedules. Do not use the health path, or a path under /__account/ or /__router/, as a handler path.

Write the handler to meet the request and response contract. The Schedule package's router implements it, and A handler without the package shows one on plain node:http.

Start schedules in each environment #

Submit the manifest, then deploy: submitting starts no run. The platform keeps one row per schedule in each environment, and a new or changed schedule starts in an environment after its next deploy there. On an application with one environment, that is the deploy to production. With two environments, it is the deploy for development and the promote for production, which your AI tool makes only when you ask.

The submit_manifest response says when each row starts. While the row waits, its next_due is null and its starts_with names what it waits for. That is the next deploy to production on an application with one environment, and the next deploy to development or the next promote to production with two. Its value is already running once the environment has a deploy or promote made at or after the declaration, with next_due set. Where that environment is halted, its value is the environment's resume instead, with next_due null, since no row of a halted environment runs until the resume.

Read and investigate runs #

Each row of the submit_manifest response also includes cron_preview, so you can check a cron before you spend a deploy. It holds up to three run times the cron yields after the submission, in UTC, and is null on an ended row. read_schedules shows the same member on every row, before its deploy and after it: up to three run times the cron yields after the read. An expression that yields fewer than three within a year shows fewer.

For 0 * * * *, they are the next three hour marks. Where the row shows deployed: true and the response shows halted: false, the platform takes them in turn, a run starting or its outcome recorded at each.

When the platform starts a run late but within the allowed delay, it uses the oldest due time. It skips later due times already passed, with no run or record for them. A delay beyond that limit records one missed run with the count of due times missed. Before the deploy the row waits for, and while the environment is halted, no run starts at them.

A due run wakes a stopped environment, such as production with production_sleep on, or a development environment, and the time to wake counts against window_seconds, so leave the handler room for it. With sleep on, production stops thirty minutes after its last request. Development always sleeps when idle. Measured on the platform, a run that woke its application took 23 to 42 seconds, and 94 seconds for the first run after a resume, in its own container. How the sizes differ technically gives the start on shared compute.

Keep a handler's state between runs in a JSON file in a declared storage area, written with a conditional put, or in the database where one is declared. Counters are write-only tallies, never state. The Schedule page shows a handler that keeps its state in a file.

A schedule runs against a deployed environment, never against a process on your machine. In a test, the schedule double starts a run (Test your application locally).

What an application must do on the Schedule page says what read_schedules shows and how it waits for a run to end. Confirm it runs in Add a scheduled job fires a run now with run_schedule. Use the run details and the logs to investigate a failure.

Skipped, missed, and unfinished runs #

The platform does not retry a failed or missed run. It skips a run in these cases:

  • another run of the schedule is in progress;
  • the account is suspended;
  • the environment has no eligible deploy;
  • the account has used its balance. The router refuses the run account_paused before any handler runs. The plane records it skipped with that name as its detail, and its due time counts nothing. The pause ends at the next UTC month's first instant.

While an environment is halted, its schedules do not run, and each next due time stays where it was. A resume restarts every schedule from the moment of the resume, and no missed run is recorded for the halt. A deploy to a halted development environment ends its halt and restarts its schedules from the deploy the same way. run_schedule on a halted environment is refused 409 target_environment_halted.

A run that is too late to start is recorded as missed and not run later. A run with no recorded end after its window is recorded abandoned, and its outcome is unknown.

Expected result #

submit_manifest returns outcome: "recorded" with the application identifier. changed says whether this manifest differs from the one recorded before it; a repeat still completes what an earlier submission left undone. deploy_reads says a deploy runs under this recorded manifest. hostnames gives each environment's hostname, where the application and its sign-in pages answer once a version serves. The kinds you declare add their own members, such as development_database and connection_limit for the database (Add a database). The rows below are the ones your AI tool acts on, and submit_manifest lists every member.

When changed is true, cost_reads points to the cost-estimate skill and read_rate_card for your AI tool to estimate cost before deploying. Read the skill with read_context, id skill:cost-estimate.

Member Returned when What it contains
detail Every submission through the MCP tool. Through the HTTP API, where the submission has something to report. What happened, one fact per line, each line a whole sentence: a line for each service the submission set up, and one naming each credential not stored yet. The last line says that only a run on your machine needs turnzero provision, and that the page in page explains each line.
settings The manifest binds a setting in settings. One row per bound setting and environment: the setting, the secret, the environment, and stored, whether the name is stored at that environment's scope. A plain setting, given as value, has no row. The rows cover only the environments the application has. detail lists each name not stored yet, for the environments the application has.
next A name a setting, an upstream, a sign-in method, or a push provider uses is stored at no scope its environment reads. One store_secret call per name and environment the detail's not-stored line counts, in that line's order, each filled in whole; make each before the deploy. A resubmission naming local_run is never listed. On an application with no development environment, an upstream key's development step, which only local runs read, is not listed either.
schedules The manifest declares the schedule kind, or a resubmission without the kind ends its schedules. One row per schedule in each environment, with starts_with, next_due, and window_seconds, the seconds a run has before the platform ends it. Each row also has cron_preview, up to three run times the cron yields after the submission, so your AI tool can check the cron before it deploys. starts_with, next_due, and cron_preview are null for an ended row. Every row of read_schedules shows up to its next three run times in cron_preview, before that deploy as well as after it, though a row starts no run before its deploy.
storage_areas The manifest's object_storage entry carries areas. One row per listed area: area, the area as list_storage_areas answers it; outcome, created or unchanged; and address, the area's whole file address with <name> in place of a file's name.

After the deploy, read_schedules shows each row of the environment it reached with deployed: true, its next_due, and reason: null; on two environments, the production rows show the same after the promote. run_schedule with wait_seconds returns the run's own outcome where it ended inside the wait, with the handler's console lines in console. read_schedules then shows that run under last_run with its outcome, status, and duration_ms.

Refusals #

See the refusals reference for other platform errors.

These parts cover submit_manifest, read_schedules, and run_schedule, with manifest_missing from deploy, the serving router's skipped run, and set_app_size's schedule conflict. A refusal gives its cause in detail. A submission refused before the manifest is recorded changes nothing. Where a row says the manifest stays recorded, the detail lists what was set up and what was not: make any change it asks for, then submit again before the next deploy or promote.

Validate the declaration and identify the application #

Refusal Status Cause Remedy
manifest_invalid 400 The manifest does not match the schema; violations lists the failing paths. An upstreams entry's line also names the refusal declare_outbound_api would give it. A realm member's or push entry's line names the refusal of configure_app_sign_in or configure_push. A listed area's line names the refusal the minting route would give it: differing_redeclaration, area_name_reserved, or area_scope_refused. A settings entry that is not exactly one of {"secret": ...} and {"value": ...}, or whose value breaks its bounds, has a line naming both forms. Correct each path and resubmit the whole manifest.
area_name_reserved 400 A listed area's reserved name became free while this manifest was being recorded. The manifest stays recorded. Choose a name that does not begin export- or deploy-, and does not match images- followed by an application's UUID. Then submit the whole manifest again.
environment_unsupported 400 The manifest has an environments member. Remove it; create_environment and delete_environment set an application's environments.
region_unavailable 400 region is europe, uk or global, which the schema admits and the platform does not serve. Set region to usa.
invalid_request 400 A member is malformed or missing, and detail names it. For read_schedules, the environment is not development or production. For the issue_tracking entry, a level or components with no space, or the platform's own space named with no components. Also a space given by an application that kept a space for each environment or has its own. Nothing is recorded. Correct the named member.
level_invalid 400 The issue_tracking entry's level is not report or contribute, or is not report beside components or for the platform's own space. Nothing is recorded. Name report or contribute, and report with a list.
no_such_application 404 application names no application of your account. Use the identifier list_applications returns.
application_other_account 403 application names an application that another account holds, not the account the call is signed in as. The detail names the account the call acted as and nothing of the other one. Compare turnzero whoami with read_account over your AI tool's connection. Make the call from the one signed in to the account that holds the application.
area_scope_refused 403 Another application claimed a listed area's name after the initial check, and this credential cannot reach that application. The manifest stays recorded. Use a new area name for this application, then submit the whole manifest again.
realm_not_declared 404 An end-user realm was deleted while this manifest was being recorded, so it was not set up. The manifest stays recorded. Submit the manifest again.
differing_redeclaration 409 A listed area was declared with different values while this manifest was being recorded. The manifest stays recorded. Use a new area name or match the existing area's values, then submit the whole manifest again.

Bind settings and configure services #

Refusal Status Cause Remedy
declared_tenant_contradicts_route 409 The workforce audience gives a different tenant from the work-account route of one of the application's realms, and the refusal's environment names which. Declare that route's tenant, or call configure_app_sign_in for the named environment with the audience's tenant (Manage end users). Where the manifest's realm member names entra, change its tenant there instead and submit again.
declared_audience_contradicts_route 409 The invited audience is declared while a realm's sign-in methods include entra, which an invitation-only realm does not allow. Remove entra from the realm's sign_in_methods and submit again, or keep the current audience. Remove it in the manifest's realm member where that names sign_in_methods, and otherwise with configure_app_sign_in (Manage end users).
setting_scope_refused 409 A binding in settings names a secret stored at account scope or at another application's scope, which no deploy of this application reads. Store the value under a new name at this application's scope, in each environment, and bind that name.
platform_minted_name 409 A binding names a credential the platform created for one of your applications. Bind a name of your own that you stored with store_secret.
setting_is_upstream_key 409 A binding names the key an upstream of the application declares; the gateway never gives that key to the application. Call the upstream through the gateway, or bind a value stored under another name.
name_bound_to_realm 409 A binding names a realm sign-in method's credential, the work-account client secret or the Apple signing key. Bind a value stored under another name; a sign-in method's credential stays the realm's.
name_bound_to_push 409 A binding names a push provider's credential of the application's push configuration. Bind a value stored under another name; a provider's credential stays the push service's.
binding_refused 409 Another application of your account declared an upstreams entry's name while this manifest was being recorded, and application names it. The manifest stays recorded. Rename the entry and submit the manifest again before the next deploy or promote.
upstream_key_is_bound 409 A binding of an upstreams entry's key was recorded while this manifest was being recorded, so the platform undid this submission's change to that entry where it could. The detail names an entry it could not undo. The manifest stays recorded. Store the key under another name and change the entry, or remove the binding, then submit the manifest again before the next deploy or promote.
not_yet_provisioned 501 The platform you reached runs no issue service, so an issue_tracking entry, one naming a space among them, sets up nothing. The manifest is recorded and every other kind is provisioned. Submit again on a platform that lists the feedback actions.
name_bound_to_setting 409 A binding of a sign-in or push credential the manifest names was recorded while this manifest was being recorded, so the platform took that credential back where this submission set it. The manifest stays recorded. Store the credential under another name and change the member, or remove the binding, then submit the manifest again.
custody_entry_missing 409 A credential named in the realm member was deleted while this manifest was being recorded, so that environment's realm was not set up. The manifest stays recorded. Store the value again, or under a new name set in the member, and submit the manifest again.
custody_entry_unmovable 409 The platform's store for sign-in credentials already contains a credential named in the realm member, at another version, so that environment's realm was not set up. The manifest stays recorded. Store the value under a new name, change the member to it, and submit the manifest again.

Deploy and run schedules #

Refusal Status Cause Remedy
no_such_schedule 404 The application has no schedule of that name in that environment. Name a declared schedule, and name the environment when it is not production.
manifest_missing 409 deploy found no manifest for the application. Submit the manifest first.
setting_secret_missing 409 A deploy or promote found a bound name not stored at its environment's scope; detail names the setting and the name, and next the store_secret call to make. Store the value there with store_secret for the application and the environment, as Store a secret describes, then deploy or promote again.
schedule_interval_below_plan 409 A schedule's due times fall closer together than schedule-minimum-interval. path names it, quantity gives the minimum in minutes, and gap the shortest gap found. Run it less often.
schedule_count_over_plan 409 The manifest declares more schedules than schedule-count-limit. path names the first one over, and quantity gives the limit. Declare fewer schedules.
plan_schedule_conflict 409 set_app_size found declared schedules that exceed the target size's limits. Submit the manifest within those limits, then repeat the size call.
plan_quantity_unset 409 A required quantity for the size is unset. The manifest stays recorded for a database, and nothing is recorded for a schedule. Read its row with read_plan_quotas and wait for platform staff to set it.
deletion_in_progress 409 The application or one of its environments is being deleted. A deletion approved while another deletion of the same application holds it ends failed with this refusal. That refusal's detail gives the instant the other deletion's hold lapses; if its process stopped, request your deletion again after that instant. Wait for the deletion to finish; read_approval_status shows whether it completed. If it failed, request the same deletion again to complete it.
schedule_not_deployed 409 run_schedule named an environment with no deploy or promote since the schedule was declared. Deploy to that environment, or promote to production on an application with two environments, then run again.
environment_not_created 409 run_schedule named development on an application with one environment. Run it in production, or turn development on with create_environment and deploy there first.
run_in_flight 409 A run of the schedule is still in progress. A due time during it is skipped, not queued. Wait until read_schedules shows the run ended, then run again.
target_environment_halted 409 run_schedule targeted a halted environment. Resume it by calling halt_environment with resume: true, then run again.
account_paused 429 The account has used its balance. The router refuses the run before the handler runs; the plane records skipped with account_paused as its detail, and the due time counts nothing. Wait until the next UTC month starts.

Provision the database and finish setup #

Refusal Status Cause Remedy
database_provisioning_failed 502 Creating the database role or password failed; the manifest stays recorded. Read the response, then resubmit to finish the setup.
server_unavailable 503 No database server has room for the database now. Or an earlier, unfinished setup recorded a server that no longer takes databases, and the setup cannot move to another server while that record exists. The manifest stays recorded. Where detail does not name a server recorded by an earlier run, resubmit later; changing the manifest does not help. Where it names one, resubmit once, since that run may still be finishing. If it repeats, delete_environment naming development removes the setup, with development's data and secrets, on one environment or two. A resubmission then sets it up again; on two environments, call create_environment before it. If that deletion fails, report the refusal with its detail, and resubmit once platform staff have removed the earlier setup or opened the server again.
cell_not_configured 503 The platform cannot place the database now; the manifest stays recorded. Nothing on your side corrects this: report the refusal with its detail, and resubmit once platform staff have configured the hosting cell.
store_unavailable 503 The platform's store did not respond while the upstreams entries or the listed areas were being declared, or while the realms or push configurations were being set up. The manifest stays recorded, and detail lists what was done and what was not. Submit the same manifest again, before the next deploy or promote.