---
title: Applications and environments
description: Understand an application's one environment or two, what each keeps apart, where each runs, the states it shows, the version history, and a halt.
slug: /concepts/applications-and-environments
order: 1
visibility: public
redirects_from: [/concepts/how-applications-are-kept-apart]
---

# Applications and environments

An application groups your hosted code, size, hostnames, and environments. It starts with `production`, so each deploy goes live directly. Add `development` with `create_environment` to test deployed changes before moving them to production with `promote`.

[Manage versions and environments](/cloud/guides/manage-versions-and-environments/) covers rollback, halt, rename, and deletion.

## Environments

An application has one environment, `production`, or two, `development` and `production`. You turn development on with `create_environment` at any time, and off again with `delete_environment`, which needs browser approval. The manifest must not declare `environments`. A manifest that does is refused `environment_unsupported`.

`create_environment` and `submit_manifest` work in either order. The submission creates development's database and credentials, and turning development on creates neither. [What submitting does](/cloud/concepts/the-manifest/#what-submitting-does) says what a submission creates in each environment, and [Test in development, then promote](/cloud/guides/turn-on-development-and-promote/) gives the steps.

Each environment has its own:

- database and role, on a development server or a production server;
- [platform credential](/cloud/concepts/glossary/#platform-credential), the value a process presents to the platform;
- secret scope, so a development request never reads a production value;
- partition in every [storage area](/cloud/concepts/glossary/#storage-area);
- end-user [realm](/cloud/concepts/glossary/#realm), hostname, and version history.

Local runs use development data and credentials even without hosted development. Declared services provide a development database, secret scope, storage partitions, and the `local` log stream. Provisioning supplies development credentials to your computer; production credentials remain on the platform.

Without hosted development, local runs use the production realm for sign-in. There is no separate development realm or deployed development copy. An action on the hosted development environment of such an application, such as `read_status`, `halt_environment`, or a realm action, is refused 409 `environment_not_created`, naming `create_environment`. The actions on the development records still work, such as `store_secret` at the development scope, `read_logs` with `local`, and `query_database` with `development`, which reads the development database.

On one environment there is nothing to promote: `promote` is refused 409 `environment_not_created`, and `roll_back` puts an earlier production version back. Once development is turned on, a deploy targets development. `deploy` with `environment: "production"` is then refused 409 `environment_unavailable`, because production receives a version only through `promote`, which applies a version from the history with production's own settings and credentials.

### What each application has of its own

Applications are isolated from one another, including applications in the same account:

- **Its image.** Each environment runs from its own application's image. On its own container, the container's identity can pull only that application's image.
- **Its platform credential.** A call made with an environment's platform credential acts for that application alone.
- **Its secrets.** A secret stored for one application cannot be read by another, and no application can read the platform's own secrets.
- **Its database.** Each environment has its own PostgreSQL database and role on the shared server, and the role keeps that database apart from every other application's.
- **Its files.** Every storage area belongs to one application. A platform credential reaches its own application's areas and no other's, and no route reaches another account's files.
- **Its external APIs.** A [declared upstream](/cloud/concepts/glossary/#declared-upstream) takes calls from its own application only, so another application's credential cannot call it with the stored key.

Your backend must also enforce access between its own users, including which files each user may read or write. See [Store files](/cloud/guides/store-files/).

### Where each environment runs

Each environment runs in one of two ways, and `list_applications` shows which in its `grain` member, `pod` or `container`:

- As one `pod` in a [group](/cloud/concepts/glossary/#grain-and-development-group) on the [hosting cell](/cloud/concepts/glossary/#hosting-cell)'s shared cluster, where the cell has a group of the environment's kind open to new environments with room left. A development environment runs this way, and so does production on Shared 0.5 GB.
- As its own `container` where the cell has no group of the environment's kind open to new environments, and always for production on Shared 1 GB. Where every open group of that kind is full, the deploy, promote, or size change is refused 409 `group_full` instead.

Either way it runs the same image with the platform's settings, and a pod also sets `HOME` to `/tmp` and runs the process as user ID (uid) 1000. [What the application runs under](/cloud/concepts/the-settings-a-deployed-copy-receives/#what-the-application-runs-under) gives the image and the user on each grain. The `grain_note` of `read_status` says what each environment's grain means.

A development environment sleeps after thirty minutes without a request, whether it runs as a pod or a container. Production sleeps after the same interval when its sleep setting is on. An environment takes a changed idle interval at its next deploy, promote or `restart_application`. A sleeping environment starts on the next request, scheduled run or deploy. Development is charged at the Shared 0.5 GB rate ([Size and usage](/cloud/guides/plan-and-usage/)).

Production keeps no idle copy where sleeping is on, or one where it is off, unless the account is paused. Each environment runs one replica, and two only while a deploy, promote or size change replaces it. Shared 1 GB production has 0.5 virtual CPU (vCPU) and 1 GiB of memory; Shared 0.5 GB has 0.25 vCPU and 0.5 GiB. A development container has 0.25 vCPU and 0.5 GiB, and a development pod takes its group's settings. [How the sizes differ technically](/cloud/concepts/how-the-plans-differ-technically/) compares their compute.

Every deploy, promote, and redeploy injects the platform's settings into the environment's copy, with that environment's values. [A deployed app's settings](/cloud/concepts/the-settings-a-deployed-copy-receives/) lists each one.

### Where an application runs during development

While you build, the application runs in up to three places, and each works differently:

- A local process on your machine, the local run, runs under the development records, on one environment or two.
- Where development is turned on, the deployed development copy runs on the platform after a deploy to it. On one environment there is no such copy, and every deploy reaches production.
- The application's tests run against the [test doubles](/cloud/concepts/glossary/#test-double) that the backend packages ship, with nothing provisioned.

| | Local process | Deployed development copy | Tests over the doubles |
| --- | --- | --- | --- |
| Environment | development, under the environment file the provision line writes | development, under the settings the deploy injects | none: a double reaches nothing outside the process |
| Database | the development database, from any address under the [developer network rule](/cloud/concepts/glossary/#developer-network-rule) | the development database | a PostgreSQL engine in the test process, with your migration files applied when it is created |
| Platform credential | the development credential | the development credential | none |
| Storage partition | the development partition of each area | the development partition of each area | the storage double, in memory |
| Secrets | the development scope's values | the development scope's values | none |
| Log stream | `local` | `development` | the logging double's entries |
| Hostname and router | no hosted hostname; the command listens in front with `--sign-in`, or with `client/` and a numeric port; otherwise the application listens directly | the development hostname, behind the serving router | none |
| Runtime harness | not loaded | loaded by the platform's image | not loaded |
| Realm keys and scheduled runs | none | injected and run by the platform where the manifest declares them | the account double signs under a key pair of its own; the schedule double starts a run |

A separate option is to [run against your own PostgreSQL](/cloud/guides/run-your-application-on-your-machine/#run-against-your-own-postgresql) on your computer, within the limits that section gives.

With development turned on, the local process and the deployed copy share the development environment's data and credential. They use the same development database, the same partition of each storage area, and the same secrets. The deployed copy keeps the credential value it started with. The provision line mints a new value, and its last step restarts the deployed copy on it.

Only the deployed copy runs behind the platform's router and [runtime harness](/cloud/concepts/glossary/#runtime-harness). It serves under the development hostname, applies the manifest's [audience](/cloud/concepts/glossary/#audience), receives the realm's public keys, and receives scheduled runs.

On your machine, `turnzero run --sign-in` relays `/__account/` requests to the application's hosted hostname. With sign-in, or with `client/` and a numeric port, the command listens in front of the application and gives it a free port as `PORT`.

Without that listener, the application uses the port its code chooses, [`PORT`](/cloud/backend-packages/nodejs-runtime/) where you set it. It verifies an end-user session through the platform's verification route, because the environment file has no realm keys. [Know what a local run reaches](/cloud/guides/run-your-application-on-your-machine/#4-know-what-a-local-run-reaches) gives the rest.

Tests use the packages' test doubles without an account, network connection, or environment file ([Test your application locally](/cloud/guides/test-your-application-locally/)). A local application that calls real platform services needs credentials, supplied through its environment or an environment file.

The platform never creates the schema. The application creates its tables from its migration files when it starts, and the same files are applied to every database it uses, as [Add a database](/cloud/guides/add-a-database/) describes.

## Environment states

In `list_applications` and `read_status`, an environment's `state` is one of six values. The state is the first of these that applies:

- `deleting`: the application or the environment is being deleted.
- `halted`: you or the platform halted the environment.
- `deploying`: a deploy, a promote, or a [platform redeploy](/cloud/concepts/glossary/#platform-redeploy) of the environment is in progress.
- `deployed`: a version is serving.
- `failed`: no version is serving, and the environment's latest deploy or promote failed.
- `never_deployed`: none of the above.

`list_applications` gives each application's `environments`, one object per environment, development first where it has one. Beside each state, `read_status` gives `compute_state`, the hosting provider's own word for the environment's compute, null until the compute exists. The response's top-level members describe one environment: the one the call names in `environment`, or production where your call leaves it out. The top-level `environment` member says which environment that is. The [read_status](/cloud/reference/actions/read-status/) and [list_applications](/cloud/reference/actions/list-applications/) reference pages list every member.

## The development hostname

You choose the application's `name` in `create_application`. The platform adds a unique suffix at creation and returns the result as `label`. You cannot choose that suffix or know the exact hostname before the call succeeds. Production uses `<label>.ai.host`; development uses `<label>-dev.ai.host`. Use the returned label and read the hostname from the platform's answers. The suffix contains no hyphen, so the two forms cannot collide. A hostname retired by deletion or renaming is never reused.

Your applications use `.ai.host`, with `<label>-dev.ai.host` for a development environment; `.dev.ai.host` belongs to tests of the platform itself.

Any application can attach one custom domain to production, a monthly item ([Attach your own domain](/cloud/guides/attach-your-own-domain/)). From when the domain first serves until you detach it, a failed state included, the production copy's `APP_PUBLIC_HOST` is that domain ([A deployed app's settings](/cloud/concepts/the-settings-a-deployed-copy-receives/)). The managed production hostname keeps serving the application, but a sign-in started on it does not complete. The development hostname is unchanged.

Read the application's hostname from `list_applications`, `create_environment`, `deploy`, or `promote` rather than composing it.

The router serves the development hostname from the moment the application is created. Before the first development deploy, it returns 404 `not_deployed` on every path except `/__account/`. On an application with one environment, that path returns 404 too, naming `create_environment`, because there is no development realm. Once development is turned on, it serves the development realm's sign-in pages where the manifest declares the `accounts` kind. So an end user can sign in to the development realm before the environment has a running copy.

Every response on the development hostname includes the header `X-Robots-Tag: noindex, nofollow`, and the platform publishes no list of development hostnames. The development environment serves your build under the manifest's audience. With `public`, anyone who knows the hostname can reach the application. Your backend must still control which data each visitor can read. [Manage end users](/cloud/guides/manage-end-users/) explains what that means for test data.

## The version history

Every deploy, promote, restart, and platform redeploy writes one row of the application's version history, which `list_versions` returns newest first. [The version history](/cloud/guides/manage-versions-and-environments/#the-version-history) says what each row's members mean, and the [list_versions](/cloud/reference/actions/list-versions/) reference lists them.

A row's `kind` says what wrote it. It is `"deploy"` for a deploy's row and `"promote"` for a promote's or rollback's row. It is `"restart"` for a row written when `restart_application`, a rename, or the platform re-created the running copy under current settings, with the same version and image. A restart keeps the application's version and image and applies current platform settings.

A deploy takes the next number of one sequence per application, shared by development and production. A promote row has the number and the harness of the deploy it promotes, because it applies that deploy's image. So a version gets the current harness only through a new deploy. A `"restart"` row has the number and harness of the row it re-created, and once it finishes it is its environment's serving row, which a promote can take. The same number can therefore appear on a development `"deploy"` row, a production `"promote"` row, and a `"restart"` row of either environment.

On one environment, a deploy's row is production's own `"deploy"` row. An environment's serving version is its newest `deployed` row. Rows that `delete_environment` retired are not returned and never serve.

## The halted state

A halted environment keeps its deployed version, its data, its credentials, and its schedule declarations, but serves nothing. Its hostname returns 503 `environment_halted` on every path, including the sign-in path `/__account/`. Its schedules do not run, and each schedule's `next_due` stays where it was.

What a halt stops:

- A halt of production stops production's compute, a container or a pod.
- Development already sleeps when idle. Its halt prevents a request or scheduled run from starting it.

A halt that stops a pod returns at once, and the pod stops within about 11 seconds. The platform waits that long so every router already returns 503 `environment_halted` when the pod stops. During some platform updates, a router can hold the pod's address longer. For up to about 19 seconds after the pod stops, a request can then reach it and wait without an answer. If the stop is cut short, the next daily check stops the pod.

Only an environment with a deployed version can be halted, so `halt_environment` refuses one with none, 409 `environment_never_deployed`. A deploy to a halted development environment ends its halt after its checks, and so does `halt_environment` with `resume: true`. Only `halt_environment` with `resume: true` ends a production halt, and until then a deploy or a promote to production is refused 409 `target_environment_halted`. A resume restarts every schedule of the environment from the moment of the resume, and no missed run is recorded.

### Halts the platform makes

Where development is turned on, the platform halts the development environment itself, with `by` set to `platform`, once its halt interval has passed. The interval runs from the later of two moments: the end of the deploy that made the environment's serving version, and the environment's last resume. So a successful deploy or a `halt_environment` with `resume: true` starts the interval again, and a deploy that ends `failed` does not.

The interval is seven days for every application, and platform staff can change it without a release. A daily check applies the rule, so the halt happens within one day after the interval ends. This automatic halt applies only to development.

The platform also re-creates an environment's running copy after it changes its [router mark](/cloud/concepts/egress-firewall-and-request-limits/#the-router-mark). This writes a `restart` row and one event in your log stream, and leaves the version and everything else of yours unchanged. A halted environment is re-created after its resume.

## Deleting, clearing, and renaming

Each of the four actions below needs a person's approval in a browser, as [The pending action](/cloud/concepts/what-happens-without-asking/#the-pending-action) describes.

### Deleting an application

`delete_application` removes every environment and everything bound to the application, as [Delete the application](/cloud/guides/manage-versions-and-environments/#delete-the-application) lists, with what the deletion keeps.

### Deleting the development environment

`delete_environment` removes the development environment alone and turns development off, so the next deploy goes to production. It refuses `production` with `invalid_request`, because production is deleted only with its application. A development environment that was never deployed can be deleted too, which removes whatever it contains, such as its realm and its secrets.

On an application with one environment there is no development environment to turn off, but your local runs keep records there. They are the development database, its platform credential, and the secrets, files, and logs you stored for them. The call is accepted when:

- a development database exists, or its setup stopped before completion, for example when `submit_manifest` refuses with `server_unavailable` or `store_secret` with `replace: true` refuses with `database_provisioning_failed`;
- an earlier deletion of these records stopped partway; the same call completes it;

It then removes those records, leaves production untouched, and the application keeps one environment. In any other case the call is refused 409 `environment_not_created`, before anything is asked of you.

The deletion removes the development environment's:

- container;
- database and role, with their credential;
- realm, with its passkeys and invitations;
- [issue-tracking space](/cloud/concepts/glossary/#issue-tracking-space), where the application kept one for each environment, deleted at the issue service with every record in it;
- binding to an issue space of your account's own, which keeps its records;
- application-scoped secrets and platform credential;
- partition of every bound storage area;
- log entries and counter totals;
- version rows, which `list_versions` no longer returns and whose numbers are never used again.

The application, its production environment, its storage areas, and its declarations remain. The secret store keeps the deleted secret values for ninety days before it purges them, and the usage meters keep their rows.

Afterwards the application has one environment, production. The next `submit_manifest` creates a new development database and role and a new development [platform credential](/cloud/concepts/glossary/#platform-credential) for local runs, and returns the development credentials once, as a first submission does. The secrets and files you stored for development are not brought back; store them again if you still need them. An application that kept an issue-tracking space for each environment also gets a new empty development space. It creates no development realm.

The development schedule declarations remain, and the schedules run again after the next development deploy. Development turned on again has a new realm where the manifest declares the `accounts` kind, and no database until the next submission, as [Delete the development environment](/cloud/guides/manage-versions-and-environments/#delete-the-development-environment) describes.

### Clearing the development database

`clear_development_database` empties the development database and keeps everything else. It drops the database with every table and row in it, then creates it again empty under the same role. The role keeps its password, so the development credential and the connection string in `.env` stay valid.

The tables come back when the application's [migrations](/cloud/concepts/glossary/#migration) run again, at the next local start or the [deployed copy](/cloud/concepts/glossary/#running-copy)'s next start, as [Add a database](/cloud/guides/add-a-database/#5-develop-locally) describes. The action refuses `production` with `invalid_request`, and an application with no development database with `not_found`.

### Renaming an application

`rename_application` takes the application identifier and a new name. The name has at most forty characters: a lowercase letter, then lowercase letters, digits, or hyphens. It must differ from the current name, or the call is refused `invalid_request`. It must also differ from the name of every other live application in the account, or the call is refused `name_taken`.

A rename permanently retires both of the application's hostnames, production's and development's, and its passkeys and invitation links stop working with them. [Rename the application](/cloud/guides/manage-versions-and-environments/#rename-the-application) lists every effect.

The rename retires exactly the hostname the approved description named. If another rename or a deletion changed the application after the approval, the outcome is `renamed: false` with the reason, and nothing changes. Read the application with `read_status`, and request the rename again if it still applies.

## Backend versions and snapshots

The application applies its own migration files when it starts, and neither a deploy nor a promote takes a snapshot. `roll_back` promotes an earlier version, restoring its code, setting bindings and plain values, and changes no data. Across a data-model change, you decide how the data is migrated or restored. Do not assume the platform has taken a snapshot or can reverse a schema change.

The catalog's two actions for this, `apply_migration` and `restore_snapshot`, are not provided by the running platform: the tool list leaves them out, and a call to either over the management route returns 501 `not_yet_provisioned`.

## Related

- [Deploy from your computer](/cloud/getting-started/deploy-an-application/) creates an application and deploys it to production.
- [Test in development, then promote](/cloud/guides/turn-on-development-and-promote/) turns on a development environment to promote from.
- [Manage versions and environments](/cloud/guides/manage-versions-and-environments/) rolls back, restarts, halts, renames, and deletes.
- [Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/) runs the application on your machine under the development records.
- [Test your application locally](/cloud/guides/test-your-application-locally/) runs the application's tests against the backend packages' test doubles.
- [A deployed app's settings](/cloud/concepts/the-settings-a-deployed-copy-receives/) lists the settings each environment's copy reads.
- [What happens without asking](/cloud/concepts/what-happens-without-asking/) explains the browser approval that `delete_application`, `delete_environment`, `clear_development_database`, and `rename_application` need.
- [Size and usage](/cloud/guides/plan-and-usage/) explains `set_app_size` and `read_usage`.
- [Actions](/cloud/reference/action-catalog/) lists every management action a customer can call, with its inputs and outputs.
