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.
The easiest way to get started is by creating a repo from the tinfoil-containers-template, which includes a pre-configured tinfoil-config.yml.
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.
Top-level fields
| Field | Type | Required | Description |
|---|
shim-version | string | Yes | Version of the Tinfoil shim, pinned with SHA256 digest |
cvm-version | string | Yes | Confidential VM version (e.g. 0.6.7) |
cpus | integer | Yes | Number of CPU cores |
memory | integer | Yes | RAM in megabytes |
containers | list | Yes | One or more container definitions |
shim | object | Yes | Port and path routing configuration |
Valid resource values
| Resource | Valid values |
|---|
| CPUs | 2, 4, 8, 16, 32 |
| Memory (MB) | 8192, 16384, 32768, 65536, 131072 |
Memory values correspond to 8 GB, 16 GB, 32 GB, 64 GB, and 128 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 |
env | list | No | Environment variables (see below) |
secrets | list | No | Secret names — values are set in the dashboard |
runtime | string | No | Container runtime — set to nvidia for GPU workloads |
gpus | string | No | GPU allocation — use all for single-GPU deployments (see note below) |
ipc | string | No | IPC mode — set to host |
volumes | list | No | Bind mounts (e.g. /mnt/ramdisk/data:/data) |
GPU configuration
NVIDIA confidential computing restricts enclaves to either 1 or 8 GPUs. For single-GPU deployments, set gpus: all. This gives the container access to the one available GPU. Specifying individual GPU indices (e.g. gpus: "0,1") is only necessary when running multiple containers in an 8-GPU enclave and splitting GPUs between them. Most deployments should use gpus: all.
Container images must include a SHA256 digest (e.g. image:tag@sha256:...). This pins the exact image binary and ensures it can be verified in the transparency log. To get the digest: docker pull <image> && docker inspect --format='{{index .RepoDigests 0}}' <image>
env:
- PORT: "8080" # Hardcoded value (YAML map syntax)
- LOG_LEVEL: "info"
secrets:
- DATABASE_URL # Looked up from your org's secrets store
- API_KEY
Routing
The shim section controls which ports and paths your container exposes.
| Field | Type | Required | Description |
|---|
shim.listen-port | integer | Yes | Always set to 443 |
shim.upstream-port | integer | Yes | Port your container listens on |
shim.paths | list | Yes | URL paths to expose (supports * wildcards) |
Examples
Minimal config
shim-version: v0.3.18@sha256:7d9f98be78c91ede89f43c948a12d084fae34312effe9395ca7ed572991cb561
cvm-version: 0.6.7
cpus: 2
memory: 8192
containers:
- name: "api"
image: "ghcr.io/myorg/api-server:v1.0.0@sha256:abc123..."
command: ["--port", "8000"]
shim:
listen-port: 443
upstream-port: 8000
paths:
- /health
- /api/*
With environment variables and secrets
shim-version: v0.3.18@sha256:7d9f98be78c91ede89f43c948a12d084fae34312effe9395ca7ed572991cb561
cvm-version: 0.6.7
cpus: 4
memory: 16384
containers:
- name: "api"
image: "ghcr.io/myorg/api-server:v2.1.0@sha256:def456..."
env:
- PORT: "8080"
- LOG_LEVEL: "info"
- NODE_ENV: "production"
secrets:
- DATABASE_URL
- STRIPE_SECRET_KEY
command: ["--port", "8080"]
shim:
listen-port: 443
upstream-port: 8080
paths:
- /health
- /api/*
- /webhooks/*
GPU inference server (vLLM)
shim-version: v0.3.18@sha256:7d9f98be78c91ede89f43c948a12d084fae34312effe9395ca7ed572991cb561
cvm-version: 0.6.7
cpus: 16
memory: 65536
containers:
- name: "inference"
image: "vllm/vllm-openai:v0.14.1@sha256:6fc52be4609fc19b09c163be2556976447cc844b8d0d817f19bc9e1f44b48d5a"
runtime: nvidia
gpus: all
ipc: host
command: [
"--model", "/models/my-model",
"--port", "8001"
]
shim:
listen-port: 443
upstream-port: 8001
paths:
- /v1/chat/completions
- /v1/completions
- /health
- /metrics
Multi-container setup
shim-version: v0.3.18@sha256:7d9f98be78c91ede89f43c948a12d084fae34312effe9395ca7ed572991cb561
cvm-version: 0.6.7
cpus: 8
memory: 32768
containers:
- name: "api"
image: "ghcr.io/myorg/api-server:v1.0.0@sha256:abc123..."
env:
- PORT: "8080"
secrets:
- DATABASE_URL
command: ["--port", "8080"]
- name: "worker"
image: "ghcr.io/myorg/worker:v1.0.0@sha256:def456..."
env:
- QUEUE_URL: "redis://localhost:6379"
secrets:
- API_SECRET
shim:
listen-port: 443
upstream-port: 8080
paths:
- /health
- /api/*
Validation
You can validate your config before deploying. In the dashboard, select your repo and tag on the Deploy tab. Tinfoil fetches your tinfoil-config.yml and checks that:
- CPU and memory values are valid
- Resource usage is within your org’s limits
- Referenced secrets exist in your org
- 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 shim-version and cvm-version values. Create a new repo from this template to get started quickly.
