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.
`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 `gpus: all`

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.

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.
`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.
`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.
`cap_add`	list	No	Linux capabilities to grant, without the `CAP_` prefix. All are dropped by default — see 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.
`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>.

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.

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. NVIDIA confidential computing restricts enclaves to those two sizes.
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:

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

Getting Started

Model catalog

Tinfoil SDKs

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

Container naming constraints

Examples

Template

​Overview

​File location

​Top-level fields

​Valid resource values

​Container spec

​GPU configuration

​Environment variable formats

​Model weights

​Validation

​Container naming constraints

​Examples

​Template

Overview

File location

Top-level fields

Valid resource values

Container spec

GPU configuration

Environment variable formats

Model weights

Validation

Container naming constraints

Examples

Template