Configuration reference

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.

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.

Top-level fields

Field	Type	Required	Description
`cvm-version`	string	Yes	Confidential VM version. Use the current value from the 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.
`networks`	object	No	Named container networks and their egress policies. See Networking & routing.
`cvm-network`	object	No	Enclave ingress settings. See Direct admin SSH.
`attested-keys`	list	No	Beta. Generate key pairs at boot and endorse their public keys. See Attested keys.
`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.
`containers`	list	Yes	One or more container definitions
`shim`	object	Yes	Port and path routing configuration. See 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.

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.
`keys`	list	No	Beta. IDs of attested keys granted to this container as read-only file mounts
`attestation`	bool	No	Beta. Enable fresh attestation requests 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.
`ipc`	string	No	`private` (default) or `none` (no `/dev/shm`). `host` is rejected.
`networks`	list	No	Networks this container attaches to. See Networking & routing.
`ports`	list	No	TCP port mappings as `"<enclave-port>:<container-port>"`. See TCP tunnels and Direct admin SSH.
`cvm_admin`	bool	No	Grant administration of the entire enclave, including other workloads and their secrets. See Direct admin SSH.
`volumes`	list	No	Named Docker volumes stored in memory, e.g. `scratch:/data`
`persistent_volumes`	list	No	Beta. Declared persistent volumes 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).
`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).
`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.
`restart`	string	No	Restart policy if the container process exits. One of `no` (default), `always`, `on-failure`, `unless-stopped`. See 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 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.

GPU configuration

GPU workloads use a two-step allocation:

Attach GPUs to the enclave with the top-level gpus field, set to either 1 or 8.
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.

Environment variable formats

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.

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 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 repo contains a ready-to-use tinfoil-config.yml and measured-release workflows. Create a new repo from this template to get started.

Getting Started

Model catalog

Tinfoil SDKs

Tinfoil Chat

Local Proxy

Tinfoil Containers

Guides

Verification & Attestation

Tutorials

Admin API

Resources

Overview

File location

Top-level fields

Valid resource values

Container spec

GPU configuration

Environment variable formats

Model weights

Validation

Instance naming constraints

Examples

Template

​Overview

​File location

​Top-level fields

​Valid resource values

​Container spec

​GPU configuration

​Environment variable formats

​Model weights

​Validation

​Instance naming constraints

​Examples

​Template

Overview

File location

Top-level fields

Valid resource values

Container spec

GPU configuration

Environment variable formats

Model weights

Validation

Instance naming constraints

Examples

Template