---
title: The manifest
description: Learn what each member of the application manifest is for, what submitting one provisions, and what changing or removing a declaration leaves in place.
slug: /concepts/the-manifest
order: 2
visibility: public
redirects_from: [/reference/manifest, /concepts/manifest]
---

# The manifest

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](/cloud/reference/sources/schemas/manifest-schema/). Validation errors identify each invalid field by its JSON path. [Author the manifest](/cloud/guides/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](/cloud/concepts/the-settings-a-deployed-copy-receives/)).

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

```json
{
  "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](/cloud/guides/add-a-database/#1-declare-it)).

| 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](/cloud/concepts/the-deploy-health-check/) requests at every deploy, promote, and [platform redeploy](/cloud/concepts/glossary/#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](/cloud/concepts/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](#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](/cloud/guides/use-the-library/#7-the-rows-in-the-manifest-member). |
| `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](#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](#upstreams-in-the-manifest). |
| `realm` | Optional. The sign-in setup of both end-user [realms](/cloud/concepts/glossary/#realm): `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](#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](/cloud/guides/use-websockets/#1-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](/cloud/guides/author-the-manifest/#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](#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](/cloud/guides/store-files/#1-declare-the-service-and-the-areas)). 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](/cloud/concepts/glossary/#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](/cloud/guides/author-the-manifest/#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](/cloud/guides/author-the-manifest/#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](/cloud/guides/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](#sign-in-and-push-in-the-manifest)) or configured afterwards with `configure_push` ([Send push notifications](/cloud/guides/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](/cloud/guides/make-sign-up-invitation-only/#3-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](/cloud/guides/add-work-account-or-apple-sign-in/#3-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](/cloud/guides/make-sign-up-invitation-only/#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](/cloud/guides/make-sign-up-invitation-only/#1-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](/cloud/concepts/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](/cloud/guides/author-the-manifest/#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](/cloud/guides/author-the-manifest/#set-a-value-that-is-not-secret) gives the plain form's rules. [Store a secret](/cloud/getting-started/store-a-secret/#bind-a-value-to-a-setting) 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](/cloud/guides/author-the-manifest/#declare-an-upstream-in-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](/cloud/guides/manage-end-users/#4-configure-the-realm) lists which realm fields the manifest owns and which `configure_app_sign_in` owns, and [Author the manifest](/cloud/guides/author-the-manifest/#configure-sign-in-and-push-in-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](/cloud/guides/publish-a-static-site/)). [The two project layouts](/cloud/concepts/what-the-deploy-zip-holds/#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](/cloud/concepts/turnzero-command/#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](/cloud/getting-started/deploy-an-application/#2-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](/cloud/guides/use-websockets/#7-deploy-and-test)).
- **Schedules.** Submission records the schedule declarations, and each starts to fire after a later deploy or promote, as [Run scheduled work](/cloud/guides/author-the-manifest/#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](/cloud/guides/author-the-manifest/#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](/cloud/concepts/glossary/#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](/cloud/concepts/turnzero-command/#running-on-your-machine) it leads to, which calls `store_secret` with `replace: true` on the development scope.

## Related

- [Author the manifest](/cloud/guides/author-the-manifest/) writes and submits a manifest, reads a refusal, and runs scheduled work.
- [Applications and environments](/cloud/concepts/applications-and-environments/) explains the environments the manifest's services are provisioned for.
- [Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/) explains what the `egress` member controls, and the observe and enforce modes.
- [Make sign-up invitation-only](/cloud/guides/make-sign-up-invitation-only/) and [Manage end users](/cloud/guides/manage-end-users/) cover what the `audience` member and the accounts service do for an application's users.
- [Use the library](/cloud/guides/use-the-library/) writes the `packages` member, by the `library take` command or by hand.
- [Glossary](/cloud/concepts/glossary/) defines the terms used on this page.
