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

# Model weights

> Prepare Hugging Face model weights for a Tinfoil Container.

## Overview

The **Models** tab prepares Hugging Face model weights for use inside a
Tinfoil Container. It does not deploy an inference server by itself. Instead,
it creates a verified model-weight artifact and gives you the `models:` block
to add to `tinfoil-config.yml`.

Use this when you are deploying a GPU inference container, such as vLLM, and
want the model weights to be pinned and verified separately from the Docker
image.

> [!NOTE]
>
> Your Docker image still needs to contain the inference server runtime. The
> Models tab prepares the weights that the runtime will load.

## Why this exists

Enclave attestation proves what code and configuration were present when the
enclave booted. Model weights are usually loaded from disk after boot, so they
need their own integrity commitment. Tinfoil uses Modelwrap to turn a pinned
Hugging Face commit into a read-only model package with a dm-verity root hash.
The enclave config commits to that root hash, and dm-verity verifies each disk
read while the inference server loads the model. For the full technical
explanation, read
[How Tinfoil Proves Exactly What Model Is Running](https://tinfoil.sh/blog/2026-02-03-proving-model-identity).

## Prepare weights

> [tab] Dashboard
>
> 1. Open the [Tinfoil Dashboard](https://dash.tinfoil.sh)
> 2. Go to **Tinfoil Containers** > **Models**
> 3. Enter the Hugging Face repo in `owner/model` form
> 4. Use the auto-filled commit, or paste a specific commit SHA
> 5. Add an HF token if the repo is gated or private
> 6. Click **Prepare weights**

> [tab] CLI
>
> Log in with an admin API key (see [Managing containers from the
> CLI](https://docs.tinfoil.sh/containers/cli.md)), pick a host from `tinfoil container hosts`, then:
>
> ```bash theme={"dark"}
> tinfoil model wrap google/gemma-4-31B-it --host gpu-host-1 --wait
> ```
>
> `--wait` polls until the job finishes and prints the generated `models:`
> block. Omit `--commit` to pin the latest commit on the repo's default
> branch, or pass a specific SHA. For gated or private repos, supply a
> Hugging Face token:
>
> ```bash theme={"dark"}
> tinfoil model wrap meta-llama/Llama-4-8B --host gpu-host-1 \
>   --hf-token-file ./hf.token --wait
> ```

Large models can take several minutes to wrap. When the job finishes, copy the
generated `models:` block into your config repo.

## Add the model block

The generated block looks like this:

```yaml tinfoil-config.yml theme={"dark"}
models:
  - name: "gemma-4-31b-it"
    repo: "google/gemma-4-31B-it@419b2efe421994fdfd3394e621983d4cc511cd4f"
    mpk: "0900ca6b913db0036792149d3ea5862986d66a6964b010e998f56fbb7e1276ab_62578683904_59fe9787-ed93-577a-9fd9-a7804c932a11"
```

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Local identifier for the model artifact |
| `repo` | string | Yes | Hugging Face repo pinned to a commit, in `owner/model@commit` form |
| `mpk` | string | Yes | Model package metadata generated by the Models tab |
| `schema` | integer | No | Pack schema the artifact was built under. Omit for schema 1. See [Pack schemas](#pack-schemas). |

The `mpk` value is generated by Tinfoil and begins with the model's root hash.
Keep it exactly as generated.

## Pack schemas

The root hash in `mpk` depends only on two inputs: the pinned Hugging Face
revision and a numbered **pack schema**. Each schema is a frozen specification
of the file layout and filesystem tooling used to build the dm-verity image, so
the same revision always produces the same bytes and root hash. The dm-verity
parameters are the same across schemas: a schema
changes how bytes are arranged, never how they are verified. The
[modelwrap](https://github.com/tinfoilsh/modelwrap) repository's
[SPEC.md](https://github.com/tinfoilsh/modelwrap/blob/main/SPEC.md) is the
authoritative registry of schema definitions.

The optional `schema` field records which pack schema was used to build the
pinned `mpk`. When omitted, it defaults to schema 1.
Set it only for packs built with schema 2 or later. The wrap API accepts
an optional `schema` parameter, and each wrap job reports the schema it used:

```yaml tinfoil-config.yml theme={"dark"}
models:
  - name: "gemma-4-31b-it"
    repo: "google/gemma-4-31B-it@419b2efe421994fdfd3394e621983d4cc511cd4f"
    mpk: "0900ca6b913db0036792149d3ea5862986d66a6964b010e998f56fbb7e1276ab_62578683904_59fe9787-ed93-577a-9fd9-a7804c932a11"
    schema: 2
```

### Reproducing a pack

Your `tinfoil-config.yml` is a public verification recipe. Anyone can rebuild
a pack from the pinned revision and declared schema with the open-source
modelwrap tool:

```bash theme={"dark"}
modelwrap --schema 2 google/gemma-4-31B-it@419b2efe421994fdfd3394e621983d4cc511cd4f
```

and compare the resulting root hash against the config's `mpk` value, the
same identity the enclave proves at runtime through remote attestation.
Each declared schema provides a self-contained recipe for reproducing the pack.

> [!NOTE]
>
> Runtime verification does not depend on the `schema` field. The enclave
> verifies every disk read against the pinned root hash regardless; the field
> exists so packs stay reproducible by third parties and tooling.

## Point your server at the mounted model

At boot, Tinfoil verifies the model artifact and mounts it read-only under
`/tinfoil/mpk`. In your inference server command, use:

```yaml tinfoil-config.yml theme={"dark"}
command: [
  "--model", "/tinfoil/mpk/mpk-0900ca6b913db0036792149d3ea5862986d66a6964b010e998f56fbb7e1276ab",
  "--served-model-name", "gemma-4-31b-it",
  "--port", "8001"
]
```

The path uses only the root hash portion of the `mpk` value:

```text theme={"dark"}
/tinfoil/mpk/mpk-<root_hash>
```

### Mounting a model in specific containers

By default every container sees the model. To restrict it, list the model's
`name` in the `models` field of each container that should have it. The model
then mounts at `/tinfoil/models/<name>` in those containers instead of
`/tinfoil/mpk`, so point `--model` there. Encrypted (`emwp`) models must be
listed this way.

## Example vLLM config

Use a vLLM image that supports your model, with `curl` available for the healthcheck.

```yaml tinfoil-config.yml theme={"dark"}
cvm-version: "<CVM_VERSION>" # TODO: Use latest version from https://github.com/tinfoilsh/cvmimage
cpus: 16
memory: 65536
gpus: 1

models:
  - name: "gemma-4-31b-it"
    repo: "google/gemma-4-31B-it@419b2efe421994fdfd3394e621983d4cc511cd4f"
    mpk: "0900ca6b913db0036792149d3ea5862986d66a6964b010e998f56fbb7e1276ab_62578683904_59fe9787-ed93-577a-9fd9-a7804c932a11"

containers:
  - name: "inference"
    image: "ghcr.io/myorg/vllm-gemma4@sha256:<digest>"
    runtime: nvidia
    gpus: all
    restart: always
    command: [
      "--model", "/tinfoil/mpk/mpk-0900ca6b913db0036792149d3ea5862986d66a6964b010e998f56fbb7e1276ab",
      "--served-model-name", "gemma-4-31b-it",
      "--port", "8001"
    ]
    tmpfs:
      /tmp: size=512m,mode=1777,exec
      /root: size=2g,mode=0700,exec
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8001/health"]
      interval: 30s
      timeout: 5s
      start_period: 30m

shim:
  upstream-port: 8001
  paths:
    - /v1/chat/completions
    - /v1/models
    - /health
```

After editing the config, commit it and trigger the **Tinfoil Release**
workflow with a new version. Wait for both phases to complete, then deploy or update
from the instances view in **Containers**.

## Updating weights

> [tab] Dashboard
>
> To update a model, prepare the new Hugging Face commit from the **Models**
> tab, replace the `repo` and `mpk` values in `tinfoil-config.yml`, then
> release a new version via the **Tinfoil Release** workflow.

> [tab] CLI
>
> `tinfoil model update` wraps a newer revision of a model that already has
> a completed wrap job on the host:
>
> ```bash theme={"dark"}
> tinfoil model update google/gemma-4-31B-it --host gpu-host-1 --wait
> ```
>
> It resolves the latest Hugging Face commit when `--commit` is not given,
> and reports "already up to date" when nothing changed. Only files that
> changed between revisions are downloaded, so updates are much faster than
> the initial wrap. When the job completes, replace the `repo` and `mpk`
> values in `tinfoil-config.yml` with the printed block and release a new
> version via the **Tinfoil Release** workflow.
>
> Once the new release is deployed, reclaim the previous artifact's disk:
>
> ```bash theme={"dark"}
> tinfoil model delete gpu-host-1 <old-job-id>
> ```

> [!TIP]
>
> Keep each model pinned to a specific Hugging Face commit. Avoid relying
> on a moving default branch for production workloads.

## Manage wrap jobs

Every prepared model is tracked as a wrap job, addressed by its host and job
ID. From the CLI:

```bash theme={"dark"}
tinfoil model list                     # wrap jobs across the organization
tinfoil model status <host> <job-id>   # poll one job; --logs includes wrap logs
tinfoil model delete <host> <job-id>   # remove a job and its artifact
```

Deleting a wrap job also removes the model artifact and download cache from
the host once no other wrap job references the same pinned revision. Deletion
is refused while the job is still running, or while any instance's
`tinfoil-config.yml` on that host references the artifact. Update or delete
that instance first.


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