> ## 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](https://docs.tinfoil.sh/containers/quickstart.md).

## 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](https://docs.tinfoil.sh/containers/private-images.md).

## Top-level fields

| Field | Type | Required | Description |
| - | - | - | - |
| `cvm-version` | string | Yes | [Confidential VM](https://docs.tinfoil.sh/verification/cvm-image.md) 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. |
| `security` | object | No | Enclave security settings. See [GPU security](https://docs.tinfoil.sh/containers/config-runtime.md#gpu-security). |
| `models` | list | No | Verified model-weight artifacts to mount in the enclave. See [Model weights](https://docs.tinfoil.sh/containers/models.md). |
| `networks` | object | No | Named container networks and their egress policies. See [Networking & routing](https://docs.tinfoil.sh/containers/config-networking.md). |
| `cvm-network` | object | No | Enclave ingress settings. See [Direct admin SSH](https://docs.tinfoil.sh/containers/config-networking.md#direct-admin-ssh). |
| `attested-keys` | list | No | **Beta.** Generate key pairs at boot and endorse their public keys. See [Attested keys](https://docs.tinfoil.sh/containers/attested-keys.md). |
| `volumes` | list | No | **Beta.** Named volume mounts. Create and attach their backing disks separately. A disk is required only for a mount with `key-secret`; other mounts may remain empty. See [Persistent volumes](https://docs.tinfoil.sh/containers/encrypted-volumes.md). |
| `containers` | list | Yes | One or more container definitions |
| `shim` | object | Yes | Port and path routing configuration. See [Routing](https://docs.tinfoil.sh/containers/config-networking.md#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 a `gpus` value |

CPU, memory, and GPU count come from this measured configuration in the
published release. Container create, deploy, and update requests cannot
override them.

> [!NOTE]
>
> Memory values correspond to 8 GB, 16 GB, 32 GB, 64 GB, 128 GB, 256 GB, and 512 GB respectively.

## Container spec

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

The format resembles Docker Compose but is not Compose. Fields such as `depends_on`, `environment`, and `network_mode` are rejected. Containers start in parallel; if one depends on another, it must retry until the other is ready.

| 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 |
| `models` | list | No | Names from the top-level `models` list to mount in this container at `/tinfoil/models/<name>`. See [Model weights](https://docs.tinfoil.sh/containers/models.md#point-your-server-at-the-mounted-model). |
| `keys` | list | No | **Beta.** IDs of [attested keys](https://docs.tinfoil.sh/containers/attested-keys.md) granted to this container as read-only file mounts |
| `attestation` | bool | No | **Beta.** Enable [fresh attestation requests](https://docs.tinfoil.sh/containers/attestation.md) for this container. Defaults to `false`. |
| `runtime` | string | No | Container runtime; use `nvidia` for GPU workloads |
| `gpus` | string/int | No | GPU allocation for this container, typically `all`. See [GPU configuration](#gpu-configuration). |
| `ipc` | string | No | `private` (default) or `none` (no `/dev/shm`). `host` is rejected. |
| `networks` | list | No | Networks this container attaches to. See [Networking & routing](https://docs.tinfoil.sh/containers/config-networking.md). |
| `ports` | list | No | TCP port mappings as `"<enclave-port>:<container-port>"`. See [TCP tunnels](https://docs.tinfoil.sh/containers/connecting.md#tcp-tunnels-and-ssh) and [Direct admin SSH](https://docs.tinfoil.sh/containers/config-networking.md#direct-admin-ssh). |
| `cvm_admin` | bool | No | Grant administration of the entire enclave, including other workloads and their secrets. See [Direct admin SSH](https://docs.tinfoil.sh/containers/config-networking.md#direct-admin-ssh). |
| `volumes` | list | No | Named Docker volumes stored in memory, e.g. `scratch:/data` |
| `persistent_volumes` | list | No | **Beta.** Declared [persistent volumes](https://docs.tinfoil.sh/containers/encrypted-volumes.md) as `<mount-name>:/mount/path`, e.g. `workspace:/workspace`. Host bind mounts are rejected. |
| `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](https://docs.tinfoil.sh/containers/config-runtime.md#security-defaults)). |
| `cap_add` | list | No | Linux capabilities to grant, without the `CAP_` prefix. Only `IPC_LOCK`, `NET_BIND_SERVICE`, and `SYS_NICE` are allowed; all are dropped by default (see [Security defaults](https://docs.tinfoil.sh/containers/config-runtime.md#security-defaults)). |
| `shm_size` | string | No | `/dev/shm` size, e.g. `2g`. Defaults to half the container's `memory` (or half the enclave's memory if no container limit is set). |
| `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](https://docs.tinfoil.sh/containers/config-runtime.md#healthchecks). |
| `restart` | string | No | Restart policy if the container process exits. One of `no` (default), `always`, `on-failure`, `unless-stopped`. See [Restart policy](https://docs.tinfoil.sh/containers/config-runtime.md#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>`.

The hostname in the image reference selects which [registry credentials](https://docs.tinfoil.sh/containers/private-images.md) are used to pull it. Images without a hostname (e.g. `vllm/vllm-openai`) are pulled from Docker Hub.

If you build your own image, publish it and commit its real digest before releasing the config. See [Building images](https://docs.tinfoil.sh/containers/building-images.md#image-digests-in-the-release-workflow).

### 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`.
2. **Expose GPUs to a container** with `runtime: nvidia` and a container-level `gpus` value; both are required together. Use `gpus: all` to give the container every GPU attached to the enclave, which 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.

Multi-GPU H100 and H200 enclaves also require an explicit opt-in to unencrypted NVLink. See [GPU security](https://docs.tinfoil.sh/containers/config-runtime.md#gpu-security).

### Environment variable formats

```yaml theme={"dark"}
env:
  - PORT: "8080"          # Literal value, measured with the config
  - LOG_LEVEL: "info"
  - FEATURE_FLAG          # Bare name: value comes from the instance's variables

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

Compose-style `KEY=value` strings and `${VAR}` interpolation are not supported. See [Secrets and environment variables](https://docs.tinfoil.sh/containers/secrets-and-env-vars.md).

## 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](https://docs.tinfoil.sh/containers/models.md) 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 instance** 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
* Volume mount names and `keyserver-url` are well formed
* The container image is accessible and includes a SHA256 digest
* The repository has a Tinfoil release workflow

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

The full runtime policy (rejected fields, capability allowlist, and so on) is enforced at deploy time, not by this check. Secrets are injected when the instance is deployed; creating or changing a secret later has no effect until you update the instance.

## Instance naming constraints

These rules apply to the instance name you choose in the dashboard or CLI, not to `containers[].name`.

| 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` and measured-release workflows. Create a new repo from this template to get started.


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