The manifest #

View this page as Markdown

On this page

An application manifest is a JSON document that declares your application's services, network access, and deployment settings. Submit the complete document with submit_manifest; it replaces the stored manifest. Deploys use that stored manifest.

Before submitting, ask your AI tool to read context://manifest_schema. Without an MCP connection, read the JSON schema at https://turnzero.ai/cloud/reference/sources/schemas/manifest.schema.json or its reference page. Validation errors identify each invalid field by its JSON path. Author the manifest gives complete examples.

The members #

The schema requires six fields and admits seven optional fields, including health. An application that runs a server still needs health. Unknown fields are rejected. Use create_environment to add development; an environments field is rejected as environment_unsupported. The server's port is also set outside the manifest: listen on PORT, which the platform sets to 8080 (Runtime settings).

For an application that runs a server and uses no services, outside hosts, or library packages, this is a complete manifest:

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

A service is one more entry in services, such as {"kind": "database"} for a database (Add a database).

Member What it declares
manifest_version The version of the manifest format, the integer 1.
services The provisioned services the application uses, each an object with a kind. The list after this table gives what each kind takes. An empty array declares no services. Hosting is not an entry, because every accepted application is hosted.
health Needed when the zip declares a start of its own; absent, health_path_undeclared refuses the act. This also applies to submit_manifest and check_manifest if either environment has a server or a server application's deploy, promote or redeploy is in flight. The health path, an absolute path on the application's own address, which the deploy health check requests at every deploy, promote, and platform redeploy. A deploy to an environment that runs no version yet is refused health_path_unserved where no source file of the zip names the path's last segment.
region Where the application runs: usa, the one region a submission accepts. The application's database, its stored files, and its logs, backups included, stay in the United States. europe, uk, and global are refused region_unavailable, and any other value is refused manifest_invalid.
egress The outbound hosts the application's own process may reach: exact lowercase hostnames and *.example.com host families. An empty array declares no external hosts. Egress firewall and request limits explains what the list controls in observe and enforce mode.
audience Who may reach the application: {"kind": "public"}, {"kind": "invited"}, or {"kind": "workforce", "tenant": …}. The invited and workforce kinds may also list session_free_paths. See The audience kinds.
packages Included library entries, each with a name and version; fonts and library/prd use a null version. Use an empty array if no entries are included. turnzero library take writes this field, creating the application manifest if needed. For a manual manifest, use the installed library's metadata or the catalog values for a chat without a folder.
settings Optional. The settings the application's code reads, as an object from a setting name to {"secret": "<stored name>"} for a stored secret or {"value": "<text>"} for a value that is not secret. Each deploy and promote injects the value stored for its environment, or the plain value as written. See Bound settings.
upstreams Optional. External APIs called through the gateway with stored keys. Each key in this object is an upstream name, and its value is that upstream's declaration. See Upstreams in the manifest.
realm Optional. The sign-in setup of both end-user realms: sign_in_methods, creation, entra, and apple, as configure_app_sign_in takes them, and clients, the native apps, one list for each environment. See Sign-in and push in the manifest.
websockets Optional. For a server, declares WebSocket upgrades, with origins, the other browser origins whose pages may open a connection. Without it every upgrade is refused. A serverless application's manifest refuses this member with serverless_no_websocket. Declare WebSockets in the manifest gives the rules for an origin.
smoke_paths Optional. One to five read-only GET routes to check after the health check passes, before a deploy or promote sends traffic to the new version. Use it for important routes whose failure should stop that switch. Leave it out to check only the health path. See Listing smoke paths.
application Optional. The application the project folder deploys to, as the lowercase UUID create_application returns. It declares nothing to the platform, which checks its form alone and does nothing else with it, and the deploy's manifest_notice leaves it out of its comparison. The turnzero command reads it before every deploy and check of the folder. See The folder's application.

Each kind of services entry takes these members besides its kind:

  • object_storage may carry areas, the storage areas each submission declares (Store files). The other three kinds, database, accounts, and email, take no other member.
  • push takes only its providers.
  • issue_tracking with no other member gives the application one issue-tracking space for both environments. It may instead give a space your account owns, one identifier or { "development": ..., "production": ... }, with a level of report or contribute. The application is then bound to that space, and nothing is created. With space at report it may also give components, one to two hundred of the space's declared component names, each once and at most 64 characters. The application's calls then reach the space under a report token limited to that list (Bind a space to some of its components).
  • custom_domain takes its domain, one lowercase hostname of at least three labels, such as app.example.com.
  • schedule takes its schedules, the declarations Run scheduled work describes.

database, accounts, and an issue_tracking entry with no space provision what they declare. The other kinds provision nothing at submission. object_storage records that the application stores files, schedule records its schedules, and a custom_domain entry declares the application's own domain for production (Attach your own domain). A push entry allows the push configuration and the push routes. Its providers are named in the entry itself (Sign-in and push in the manifest) or configured afterwards with configure_push (Send push notifications).

The email service is available to every application. A schedule service entry must include its schedules array.

The audience kinds #

  • Public. Anyone can reach the application.
  • Invited. Every request needs an end-user session. The application's realms become invitation-only: a first sign-in without an invitation from invite_end_user with email creates no user, whatever the realm's creation setting is. The owner needs an invitation for their first sign-in too, using any address they can read mail at (Invite each person).
  • Workforce. Only one company's staff can reach the application. The tenant member is the identifier (a GUID) of the company's work-account tenant. The realm's entra sign-in method is configured against that tenant, as Allow only one company's staff describes. Only that tenant's signed-in users reach the application.

For a whole app or one page restricted to its owner, see A page for the owner alone.

Under invited and workforce, a request without an end-user session is refused. There are two exceptions: the platform's own scheduled runs, and the paths the audience lists in session_free_paths. A payment provider's webhook, or any other service's callback, has no session, so list its path there to receive it. The platform checks nothing about the sender on a listed path, so the route checks each caller itself, by the provider's signature. Choose who may sign up gives the rules for the list.

For invited and workforce applications, the router rejects other requests without a session before they reach your server. Keep your server's session checks for local runs and tests, which have no platform router.

The deploy health check calls the health path from inside the platform, and the sign-in check never refuses it. So a deploy passes without listing the health path. List it in session_free_paths only where something outside the platform must probe it, such as an uptime monitor. The path, and every path below it, then answers anyone, so return nothing there that you would not show anyone.

Where the manifest of an application that runs a server declares health, the health.gated member of submit_manifest's answer says whether the sign-in check covers the path for a request from outside. Otherwise the answer has no health member.

Bound settings #

The settings member declares each setting the application's code reads, and it is reviewed and versioned with the code. Each entry takes one of two forms:

  • {"secret": "<stored name>"} binds a stored secret. The binding names the secret, never its value, and each environment reads the value stored at its own scope.
  • {"value": "<text>"} sets a value that is not secret, such as a page title. The value is the same in every environment, at most 4,096 characters, with no line break or other control character. A secret never goes here: the manifest and each version's record keep the value as written.

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.

Bind a stored value to a setting gives the worked example, when a replaced value takes effect, and each refusal, and Set a value that is not secret gives the plain form's rules. Store a secret compares a binding with the gateway.

Upstreams in the manifest #

An upstream is an external API called through the gateway, which adds its stored key. Declaring it in the manifest avoids a separate declare_outbound_api call. Each entry accepts that action's fields except application; submit_manifest identifies the application.

Upstream names must be unique within your account. When copying an application into the same account, give its upstreams new names. A name already used by another application is rejected. The refusal names that application.

While the member lists an upstream, the manifest controls it, and declare_outbound_api refuses to change it. An upstream the member does not list can still be changed with declare_outbound_api. No submission ends an upstream, so a running version that calls it keeps working. declare_outbound_api with remove: true ends one once the member no longer lists it. Author the manifest shows the member and its refusals.

Sign-in and push in the manifest #

The realm member declares the sign-in setup that is the same in every environment: the sign-in methods, who may create an account, and the entra and apple route members. Its clients declares the native apps that sign in, with one list for each environment, each list going to that environment's realm alone. A push entry in services may also name its providers, apns and fcm. Each credential member names a stored secret, never its value.

With these members and upstreams, re-creating an application, or copying it into another account, takes the manifest, a store_secret for each credential and key, and a deploy. What the manifest names needs no configure_app_sign_in or configure_push call. Set the limits, the session lengths, each native client's minimum version and update URL, and Apple's push gateway again where they differ from the defaults.

While the manifest names a field, it controls that field, and configure_app_sign_in or configure_push refuses to change it. The settings that differ by environment stay with the actions: a realm's limits, session lengths, and invitation days, each native client's minimum version and update URL, and Apple's push gateway. Configure the realm lists which realm fields the manifest owns and which configure_app_sign_in owns, and Author the manifest shows the members.

The folder's application #

The application member binds the project folder to the application it deploys to. The turnzero command reads the folder's manifest.json before every deploy and check, before it zips the folder or sends anything. Where the command's --application names another application, or the member is not an application id, the command ends with status 3 and nothing is sent. So a copied project that names another account's application is refused too.

The scaffold command writes the member where it names --application. Otherwise the first deploy that goes on to upload writes it and prints a bound: line. A binding: line comes right before that write. To deploy the folder to another application on purpose, ask the account's owner, then change or remove the member. Development and production are environments of one application, so the member covers both.

Keep the member in the manifest you pass to submit_manifest once the scaffold or a deploy writes it. The platform checks only its form and records the manifest for the application the call names. A submission without the member is admitted too, and a deploy's manifest_notice leaves the member out of its comparison.

For a server, the folder's top holds package.json and manifest.json. In a server project with an app/ folder, both sit in app/, with the code, and the library folder system/ sits beside app/. A static site's folder holds manifest.json and client/; it needs no package.json (Publish a static site). The two project layouts shows both forms. Run turnzero hash in that folder to build the zip a deploy would, with no sign-in: it sends nothing and prints the folder's warnings (Checking a deploy).

What submitting does #

submit_manifest records the manifest for an application, then provisions the implemented services it declares:

  • Database. The first database declaration creates the development database and its role at submission, on every application, for local runs. While the manifest declares the kind, the first deploy to production creates the production database and role on one environment, and the first promote creates them on two.
  • Accounts. The first accounts declaration creates an end-user realm for each environment the application has: production's alone on one environment. The production realm stays until the application is deleted. A development realm is created by create_environment or by a submission while development is on, and ends with delete_environment or with the application.
  • Credentials. The first submission creates a development platform credential and, when a database is declared, its credential. No production credential is ever returned. Declare the manifest says how your AI tool receives them, and how the provision command writes them for a local run.
  • Bound settings. A settings member provisions nothing. The result's settings rows say, per bound setting and environment the application has, whether the bound name is stored there yet. A plain setting has no row.
  • Upstreams. An upstreams member declares each upstream, as declare_outbound_api would, from that moment. A key not stored yet is accepted. The result's upstreams rows say, per upstream and environment, whether its key is stored there. When an entry drops its key setting, the platform ends the egress keys that running copies have for its upstream, and egress_keys_ended counts them. A detail line names each environment that lost one and how to restore it: restore sdk_settings.key, submit, then call restart_application there. Where the egress list admits an upstream's host, the result carries egress_notice.
  • Sign-in and push. A realm member configures the realm of each environment the application has, and a push entry's providers configure each of those environments, as the two actions would. On one environment that is production alone, and create_environment configures development when it adds it. A credential not stored yet is accepted. The result's detail names each one not stored yet, with the environment where only one environment lacks it.
  • WebSockets. A websockets member provisions nothing. The serving router reads it within about 30 seconds. Both Shared 0.5 GB and Shared 1 GB then admit upgrades from the origins the declaration allows, on shared compute and in their own container (Deploy and test).
  • Schedules. Submission records the schedule declarations, and each starts to fire after a later deploy or promote, as Run scheduled work describes.

Validation finishes before provisioning starts. Provisioning can still fail partway through, leaving the manifest saved and some resources created. Follow the response's retry instructions; Reading a refusal explains this case.

check_manifest runs the same validation and lists the paths added, removed, and changed without recording the manifest or setting up services. It does not predict refusals during setup or custom domain writes. It does not predict the sign-outs or invalidation of held codes for test end users caused by changing to a work-account audience or another tenant.

Changing the manifest #

Change the manifest through submit_manifest, and send the whole document. A submission replaces the recorded manifest, so a member you leave out removes that declaration. A deploy reads the recorded manifest and does not change it. The manifest-author skill writes or changes a manifest against the published schema, and the add-service skill adds a service declaration.

Removing a declaration deletes nothing:

  • A removed database, with its role, remains until delete_environment removes the development database or delete_application removes both.
  • A removed accounts declaration leaves each realm in place on the same terms.
  • A removed schedule declaration runs no more, and its run records are kept.
  • A removed upstream entry stays declared, and declare_outbound_api can change it again. It ends when you call declare_outbound_api with remove: true, or when the application or your account is deleted. Promote the version that no longer calls it first. 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.
  • A removed realm field or push provider keeps its configuration, and configure_app_sign_in or configure_push can change it again.
  • If you remove websockets or an allowed origin, the router refuses new WebSocket connections that the removed declaration allowed. It also closes existing connections that depended on that declaration with code 1008, within about 30 seconds.

A binding or a plain value added, changed, or removed takes effect at the environment's next deploy or promote. A restart re-applies the bindings and plain values the running copy was started with, never the current manifest's. A rollback restores the bindings and plain values that version last used in production. If production never ran the version, the rollback uses the settings recorded at its deploy.

The platform gives a deployed copy what the environment has, not what the manifest declares. While a database remains, each deploy or promote supplies the connection string of the environment it reaches. While a realm remains, the deploy and the promote still supply its public keys. A production deploy or promote creates a missing production database only if the manifest declares the database service. If you remove that declaration, an existing database is reused. If no database remains, declare the service again; the next production deploy or promote creates the database.

Submitting an unchanged manifest records it again. Where the development database and the development platform credential already exist, it provisions nothing new and creates no credential. New development credentials come from turnzero provision --application <application id>, run with nothing piped, and the provision command it leads to, which calls store_secret with replace: true on the development scope.