> ## 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.

# Secrets & environment variables

> Manage environment variables and secrets for your Containers.

## What to use when

Tinfoil Containers supports two different kinds of configuration values:

<Warning>
  Secret values are accessible to Tinfoil infrastructure during deployment. If your threat model requires that Tinfoil cannot access certain values, [contact us](mailto:contact@tinfoil.sh) about your use case.
</Warning>

|                | Environment variables                                   | Secrets                                                    |
| :------------- | :------------------------------------------------------ | :--------------------------------------------------------- |
| **Stored in**  | `tinfoil-config.yml` (in your repo)                     | Encrypted storage (AWS Secrets Manager)                    |
| **Visible to** | Anyone with repo access                                 | **Tinfoil infrastructure**, no public access               |
| **Set via**    | Config file                                             | Declared in config; values managed in the dashboard or CLI |
| **Use for**    | Non-sensitive config (ports, log levels, feature flags) | Sensitive values (API keys, database URLs, tokens)         |

<Note>
  Environment variables and secrets are both *declared* in the config. Env var values are also set in the config file; secret values are managed in the dashboard or CLI.
</Note>

Declaring a secret in `tinfoil-config.yml` and selecting it for a deployment are separate steps. The declaration identifies the environment variable expected by the container. During deployment, select every declared secret that should be injected. With the CLI, pass each name using `--secret NAME`.

## Environment variables

### Config File

Define environment variables in the `env` field of your container configuration file:

```yaml tinfoil-config.yml theme={"dark"}
containers:
  - name: api
    image: "ghcr.io/myorg/api-server:v1.0.0@sha256:<digest>"
    env:
      - PORT: "8080"
      - LOG_LEVEL: "info"
      - NODE_ENV: "production"
```

### Dashboard

During deployment, the dashboard displays the environment variables (and secret names) defined in your `tinfoil-config.yml`. These values are read-only. To change them, update the config file in your repo and release a new version via the **Tinfoil Release** workflow.

### Reserved variables

`DOMAIN` is a reserved environment variable set to your container's public domain. Tinfoil populates it automatically at deploy time and uses it to bind the enclave's attested identity and TLS certificate to your domain, and to scope request validation. You don't need to set it — and you shouldn't define your own `DOMAIN` in `env`, since it's managed for you.

## Secrets

Secrets are stored in AWS Secrets Manager and injected into your container as environment variables at deploy time. They are not exposed in the dashboard UI or your Git repository.

### Scopes

Organization secrets are available to every repository in your organization. Repository secrets are available only to containers deployed from one `owner/repo`.

The same name can exist in different repositories, with a different value in each. A name cannot be shared between organization and repository scope within the same organization.

### Creating

To create an organization secret:

1. Go to the **Secrets** tab in the Containers section of the dashboard
2. Click **Add Secret**
3. Enter a name (e.g. `DATABASE_URL`) and value
4. Click **Save**

To create a repository secret, open the repository in the **Repositories** tab and add it in the **Repository secrets** section.

### Referencing

List secret names in the `secrets` field of your container spec. At deploy time, Tinfoil resolves each name from the container's repository secrets or the organization secrets:

```yaml tinfoil-config.yml theme={"dark"}
containers:
  - name: api
    image: "ghcr.io/myorg/api-server:v1.0.0@sha256:<digest>"
    env: # ...
    secrets:
      - DATABASE_URL
      - STRIPE_SECRET_KEY
```

When deploying a container, the dashboard shows which secrets your config references. If your config references a secret that doesn't exist yet, the dashboard warns you and prevents deployment until it's created.

### Updating

Edit a secret's value in the **Secrets** tab or the repository's **Repository secrets** section at any time. Updating a secret does **not** automatically update running containers. To pick up the new value you must redeploy. Redeployment uses the [blue-green flow](/containers/updates), so there's no downtime.

<Tip>
  The dashboard shows a **stale secrets** indicator on containers that were deployed before their secrets were last updated.
</Tip>

### Deleting

You cannot delete a secret that is referenced by any container in its scope. The dashboard shows which containers are using it. Remove the secret from those deployments, then delete it.

### Using the CLI

The [Tinfoil CLI](/containers/cli) manages organization secrets with `tinfoil secret`:

```bash theme={"dark"}
tinfoil secret list

# Create — read the value from a file or stdin to avoid shell history
tinfoil secret create DATABASE_URL --value-file ./db.url
echo -n "$STRIPE_KEY" | tinfoil secret create STRIPE_SECRET_KEY --value-file -

# Rotate (containers using it are marked stale; redeploy to pick up the new value)
tinfoil secret set DATABASE_URL --value-file ./db.url

# Inspect (the value itself is never returned)
tinfoil secret get DATABASE_URL

# Delete (fails if any container references it)
tinfoil secret delete DATABASE_URL
```

Use `tinfoil repo secret` for repository secrets:

```bash theme={"dark"}
tinfoil repo secret list myorg/my-app-config
tinfoil repo secret create myorg/my-app-config DATABASE_URL --value-file ./db.url
tinfoil repo secret set myorg/my-app-config DATABASE_URL --value-file ./db.url
tinfoil repo secret get myorg/my-app-config DATABASE_URL
tinfoil repo secret delete myorg/my-app-config DATABASE_URL
```

Reference secrets at deploy time with `--secret NAME` on `tinfoil container create`, `relaunch`, or `start`. See the [CLI secrets section](/containers/cli#secrets) for details.