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

# Configuration reference

> The tinfoil-config.yml file declares everything that runs inside your enclave: containers, resources, models, and routing. Tinfoil measures it and publishes the measurement so clients can verify exactly what is deployed.

## Overview

Every Tinfoil Container requires a `tinfoil-config.yml` file in the root of your GitHub repository. This file defines the enclave runtime, resource allocation, container configuration, and request routing.

For a pre-filled `tinfoil-config.yml`, follow along with the [quickstart guide](/containers/quickstart).

## File location

The file must be named `tinfoil-config.yml` and placed at the root of your repository. Tinfoil fetches this file from GitHub when you deploy or validate a container.

The repository must be public. Tinfoil measures your config at each tag and publishes the measurement to the Sigstore transparency log, so clients can verify against it. The Docker image the config references can still be private — see [Private images](/containers/private-images).

## Top-level fields

| Field         | Type    | Required | Description                                                                                                                   |
| ------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `cvm-version` | string  | Yes      | Confidential VM version. Use the current value from the [template](https://github.com/tinfoilsh/tinfoil-containers-template). |
| `cpus`        | integer | Yes      | Number of CPU cores                                                                                                           |
| `memory`      | integer | Yes      | RAM in megabytes                                                                                                              |
| `gpus`        | integer | No       | Number of GPUs to attach to the enclave (`1` or `8`). Omit for CPU-only workloads.                                            |
| `models`      | list    | No       | Verified model-weight artifacts to mount in the enclave. See [Model weights](/containers/models).                             |
| `networks`    | object  | No       | Named container networks and their egress policies. See [Networking & routing](/containers/config-networking).                |
| `containers`  | list    | Yes      | One or more container definitions                                                                                             |
| `shim`        | object  | Yes      | Port and path routing configuration. See [Routing](/containers/config-networking#routing).                                    |

### Valid resource values

| Resource        | Valid values                                                                             |
| --------------- | ---------------------------------------------------------------------------------------- |
| **CPUs**        | 2, 4, 8, 16, 32                                                                          |
| **Memory (MB)** | 8192, 16384, 32768, 65536, 131072, 262144, 524288                                        |
| **GPUs**        | 1 or 8 at the top level; each GPU container also needs `runtime: nvidia` and `gpus: all` |

<Info>
  Memory values correspond to 8 GB, 16 GB, 32 GB, 64 GB, 128 GB, 256 GB, and 512 GB respectively.
</Info>

## Container spec

Each entry in the `containers` list defines a container to run inside the enclave.

| Field          | Type       | Required | Description                                                                                                                                                                      |
| -------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string     | Yes      | Container identifier                                                                                                                                                             |
| `image`        | string     | Yes      | Docker image with SHA256 digest (e.g. `image:tag@sha256:...`)                                                                                                                    |
| `command`      | list       | No       | Command arguments passed to the container                                                                                                                                        |
| `entrypoint`   | list       | No       | Override the container's entrypoint                                                                                                                                              |
| `working_dir`  | string     | No       | Override the working directory                                                                                                                                                   |
| `user`         | string     | No       | Run as a specific `uid:gid`. Defaults to the image's user.                                                                                                                       |
| `env`          | list       | No       | Environment variables (see below)                                                                                                                                                |
| `secrets`      | list       | No       | Secret names — values are managed in the dashboard or with the CLI                                                                                                               |
| `runtime`      | string     | No       | Container runtime — set to `nvidia` for GPU workloads                                                                                                                            |
| `gpus`         | string/int | No       | GPU allocation for this container — typically `all`. See [GPU configuration](#gpu-configuration).                                                                                |
| `ipc`          | string     | No       | IPC mode — set to `host`                                                                                                                                                         |
| `pid`          | string     | No       | PID namespace — `host` to share the host PID namespace (rare, security-sensitive)                                                                                                |
| `networks`     | list       | No       | Networks this container attaches to. See [Networking & routing](/containers/config-networking).                                                                                  |
| `volumes`      | list       | No       | Bind mounts (e.g. `/mnt/ramdisk/data:/data`)                                                                                                                                     |
| `devices`      | list       | No       | Host device passthrough (e.g. `/dev/dri:/dev/dri`)                                                                                                                               |
| `tmpfs`        | map        | No       | Writable in-memory mounts, e.g. `/tmp: "size=100m"`. Useful with a read-only root filesystem.                                                                                    |
| `read_only`    | bool       | No       | Read-only root filesystem. **Defaults to `true`** — see [Security defaults](/containers/config-runtime#security-defaults).                                                       |
| `cap_add`      | list       | No       | Linux capabilities to grant, without the `CAP_` prefix. All are dropped by default — see [Security defaults](/containers/config-runtime#security-defaults).                      |
| `security_opt` | list       | No       | Extra Docker security options. `no-new-privileges:true` is always applied.                                                                                                       |
| `shm_size`     | string     | No       | Shared-memory size, e.g. `2g`. (defaults to 50% of the container's `memory`)                                                                                                     |
| `memory`       | string     | No       | Memory limit for this container, e.g. `512m`                                                                                                                                     |
| `cpus`         | float      | No       | CPU limit for this container, e.g. `2.0`                                                                                                                                         |
| `pids_limit`   | integer    | No       | Max processes/threads. **Defaults to `65536`**; `-1` for unlimited.                                                                                                              |
| `healthcheck`  | object     | No       | Docker-style healthcheck run inside the container. See [Healthchecks](/containers/config-runtime#healthchecks).                                                                  |
| `restart`      | string     | No       | Restart policy if the container process exits. One of `no` (default), `always`, `on-failure`, `unless-stopped`. See [Restart policy](/containers/config-runtime#restart-policy). |
| `stop_signal`  | string     | No       | Signal used to stop the container (e.g. `SIGTERM`)                                                                                                                               |
| `stop_timeout` | integer    | No       | Seconds to wait before force-killing on stop                                                                                                                                     |

The `image` field must include a SHA256 digest (e.g. `image:tag@sha256:...`), not only a mutable tag such as `:latest`. The digest pins the exact image binary and ensures it can be verified in the transparency log. To get the digest, run `docker pull <image> && docker inspect --format='{{index .RepoDigests 0}}' <image>`.

<Note>
  If you build your own image as part of the release workflow, use a placeholder digest (`sha256:0000...`) on `main` — the release workflow substitutes the real digest into the tagged commit. See [Building images](/containers/building-images#image-digests-in-the-release-workflow).
</Note>

### GPU configuration

GPU workloads use a two-step allocation:

1. **Attach GPUs to the enclave** with the top-level `gpus` field, set to either `1` or `8`. NVIDIA confidential computing restricts enclaves to those two sizes.
2. **Expose GPUs to a container** with `runtime: nvidia` and a container-level `gpus` value. Use `gpus: all` to give the container every GPU attached to the enclave — this is the right choice for both single-GPU and most multi-GPU setups. Individual indices (e.g. `gpus: "0,1"`) are only needed when running multiple containers in an 8-GPU enclave and splitting GPUs between them.

GPU containers typically also set `ipc: host` so the NVIDIA runtime can share memory with host processes.

### Environment variable formats

Environment variables support two formats:

```yaml theme={"dark"}
env:
  - PORT: "8080"          # Hardcoded value (YAML map syntax)
  - LOG_LEVEL: "info"

secrets:
  - DATABASE_URL           # Looked up from repository or organization secrets
  - API_KEY
```

## Model weights

GPU inference containers often need large model weights in addition to the
Docker image that runs the server. Use the top-level `models` list to mount
verified model-weight artifacts prepared in the dashboard's **Models** tab. See
[Model weights](/containers/models) for the field reference, the preparation
workflow, and a complete vLLM example.

## Validation

You can validate your config before deploying. In the dashboard, click **New Container** and select your repo and tag. Tinfoil fetches your `tinfoil-config.yml` and checks that:

* CPU, memory, and GPU values are valid
* Resource usage is within your org's limits
* Model weight references are valid when `models` is set
* Referenced secrets exist for the repository or organization
* The container image is accessible and includes a SHA256 digest

If validation fails, the dashboard shows specific error messages explaining what needs to be fixed.

## Container naming constraints

| Constraint         | Rule                                                                   |
| :----------------- | :--------------------------------------------------------------------- |
| Allowed characters | Lowercase letters, numbers, hyphens                                    |
| Start/end          | Cannot start or end with a hyphen                                      |
| Max length         | 64 characters                                                          |
| Uniqueness         | Unique per organization (production and debug namespaces are separate) |

### Examples

| Name                | Valid?                          |
| :------------------ | :------------------------------ |
| `my-api`            | Yes                             |
| `data-processor-v2` | Yes                             |
| `MyAPI`             | No — uppercase not allowed      |
| `my_api`            | No — underscores not allowed    |
| `my api`            | No — spaces not allowed         |
| `-my-api`           | No — cannot start with a hyphen |
| `my-api-`           | No — cannot end with a hyphen   |

## Template

The [tinfoil-containers-template](https://github.com/tinfoilsh/tinfoil-containers-template) repo contains a ready-to-use `tinfoil-config.yml` with the latest `cvm-version` value. Create a new repo from this template to get started quickly.