Skip to main content

​
Prerequisites

  • An organization created in the Tinfoil Dashboard (Containers is an org-level feature)
  • A Docker image published to a container registry
Tinfoil does not build your container — you need to bring your own Docker image. If you haven’t published one yet, see GitHub’s guide on publishing Docker images to GitHub Container Registry.

​
Step 0: Build and publish your Docker image

Before using Tinfoil Containers, you need a Docker image published to a container registry. Any registry that supports Docker images will work:

​
Step 1: Create a repo from the template

On GitHub, click Use this template (make sure you’re signed in) → Create a new repository. Your new repo includes a pre-configured tinfoil-config.yml. Use Template
For a working example, see tinfoilsh/tinfoil-containers-hello-world — a minimal hello-world container that responds with a fixed message.

​
Step 2: Configure your container

Edit tinfoil-config.yml in your new repo. Replace the placeholder container image with your own and update the paths your app exposes:
tinfoil-config.yml
cvm-version: <CVM_VERSION>
cpus: 2
memory: 8192

containers:
  - name: "app"
    image: "<YOUR_CONTAINER_IMAGE>@sha256:<SHA256_DIGEST>" # e.g. ghcr.io/myorg/my-app:v1.0.0@sha256:abc123...
    env:
      - PORT: "8080"
    secrets:
      - DATABASE_URL
    command: ["--port", "8080"]

shim:
  upstream-port: 8080
  paths:
    - /<YOUR_ENDPOINT>
Container images must include a SHA256 digest (e.g. image:tag@sha256:...). This ensures the exact image is verified and recorded in the transparency log. Get the digest with: docker pull <image> && docker inspect --format='{{index .RepoDigests 0}}' <image>
See the configuration reference for all available options.

​
Step 3: Tag a release

Commit your config and push a Git tag: 
git add tinfoil-config.yml
git commit -m "Configure my-app deployment"
git tag v0.0.1
git push origin main --tags
Each tag publishes a measured release and creates an auditable record in the Sigstore transparency log.

​
Step 4: Add secrets

If your container uses secrets (like DATABASE_URL above), add them before deploying:
  1. Open the Tinfoil Dashboard
  2. Navigate to Tinfoil Containers > Secrets tab
  3. Click Add Secret, enter the name and value
  4. Secret values are encrypted and only accessible inside the enclave

​
Step 5: Deploy your container

  1. In the All Containers tab, click Create Deployment
  2. Enter a name for your container (lowercase, hyphens allowed — e.g. my-api)
  3. Select your repository — either enter owner/repo manually or pick from your connected GitHub repos
  4. The latest Git tag you just pushed (e.g. v0.0.1) will automatically get selected.
  5. Any env vars and secrets that your config contains will automatically show up.
  6. Click Deploy Container

​
Step 6: Wait for deployment

The dashboard shows your container as Deploying while the image is pulled and the enclave boots. This typically takes a few minutes to even 15+ minutes for enclaves with GPUs. Once it’s ready, the status changes to Running. If something goes wrong, it shows Failed.

​
Step 7: Access your container

Once the status shows Ready, your container is live at: 
https://<name>.<org>.containers.tinfoil.dev
The exact URL is shown in the dashboard on the container’s card. Click the copy button to grab it. You can now use one of the SDKs to make attested HTTP requests to your exposed endpoints.

​
Updating your container

To deploy a new version, update tinfoil-config.yml (e.g. change the image tag), commit, and push a new Git tag: 
git add tinfoil-config.yml
git commit -m "Update image"
git tag v0.0.2
git push origin main --tags
If you included the GitHub Actions workflow from the template, this automatically creates a pre-release on GitHub. Then in the dashboard, click Update on your container, select the new tag in the modal, and confirm. This triggers a blue-green update. If you connected the repo via GitHub (recommended), the pre-release is automatically promoted to a release once the update completes. If you connected manually, you need to promote the release in your config repo yourself or attestation will fail.
Enable Auto-update on tag push (available for GitHub-connected repos) to automatically trigger the full update flow whenever you push a new tag.

​
What’s next

Configuration Reference

All tinfoil-config.yml options.

Secrets & Env Vars

Manage environment variables and encrypted secrets.

Deployments

Blue-green updates, redeployments, and cloning.

Debug Mode

SSH into your container for troubleshooting.