> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinfoil.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Instance lifecycle

> How an instance moves between Running and Stopped, and the actions that move it.

## Instance lifecycle

An instance is either running or it is not. Instances move through these states; the dashboard and CLI use sentence-case labels for API statuses, with `started` displayed as **Starting**:

| Status | Description |
| - | - |
| **Pending** | Deployment is queued |
| **Deploying** | Image is being pulled and the enclave is booting |
| **Starting** | The enclave is running and startup checks are still in progress (API: `started`) |
| **Running** | The instance is live and serving traffic |
| **Failed** | Something went wrong; check your config and Docker image |
| **Stopping** | The enclave is shutting down |
| **Stopped** | No enclave is running; the saved configuration and attached volumes remain |

Three actions move an instance between these states:

* **Deploy** boots a new enclave for an instance that has none: one that is Stopped, Failed, or still Stopping (the deploy runs once the stop finishes). It uses the saved configuration unless you change it first.
* **Update** replaces the version a Running instance serves. Depending on the instance it either boots the new version alongside the current enclave or stops it first; see [Updating](/containers/updates).
* **Stop** shuts the enclave down, moving the instance through Stopping to Stopped.

To run the same version on a fresh enclave, Update a blue/green instance to its current tag (no downtime), or Stop and then Deploy any instance (downtime).

The dashboard polls for status updates automatically and updates the project counts.

## Stopping and deploying an instance

Open an instance's actions in the dashboard and click **Stop** to shut down its enclave. Its DNS records are removed so it is unreachable while stopped; its saved configuration and volumes are kept. Click **Deploy** to bring it up again. The deploy dialog lets you pick a different version or edit the configuration first, and for a Failed instance it shows the last error so you can fix it before trying again.

Stopped is not a suspended memory image. Deploy boots a new enclave from the saved configuration and resolves current secret values. With `key-secret` and private-keyserver delivery, automatic unlock depends on the keyserver releasing the key after attestation. An attached disk at a mount without `key-secret` still needs the application's manual unlock flow; an empty optional mount provides no persistent storage. Deployment alone is not proof that a retained disk is usable. See [storage prerequisites](/containers/encrypted-volumes#before-deploying-with-storage). In-memory state and ephemeral filesystem writes do not survive Stop.

## Deleting an instance

Click **Delete** on an instance to permanently remove it. This:

* Stops the running enclave
* Cancels any in-progress update
* Deletes the instance's secret bindings
* Removes the instance from your org
* Retains managed volumes as unattached disks; delete those volumes separately to erase their data

<Warning>
  Deletion is irreversible. The instance's configuration, secret bindings,
  and environment variables are permanently removed.
</Warning>

## Using the CLI

The [Tinfoil CLI](/containers/cli) exposes both project-level inspection and the individual instance lifecycle:

```bash theme={"dark"}
tinfoil project list                          # projects and instance counts
tinfoil project get owner/repo                # one project
tinfoil container create my-api --repo owner/repo --tag v1.0.0
tinfoil container list                  # all instances in the org
tinfoil container get my-api            # full detail (status, host, resources)
tinfoil container stop my-api           # shut down; keep config and volumes
tinfoil container deploy my-api         # bring a stopped or failed instance up
tinfoil container update my-api --tag v1.0.1   # replace the running version
tinfoil container delete my-api         # permanent; prompts unless --yes
```

See the [CLI reference](/containers/cli) for create flags, update controls, and scripting tips.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.