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

# Runtime & security

> Security defaults applied to every container, plus healthchecks and restart policies that govern the container lifecycle.

## Security defaults

The enclave applies hardened defaults to every container, so the attested config honestly reflects what runs. These differ from stock Docker, so a container that relied on Docker's permissive defaults may need adjustment.

| Behavior | Default | How to change it |
| - | - | - |
| **All capabilities dropped** | Containers start with zero Linux capabilities. | Add what you need with `cap_add`; only `IPC_LOCK`, `NET_BIND_SERVICE`, and `SYS_NICE` are allowed. There is no `cap_drop`. |
| **No new privileges** | `no-new-privileges:true` is always set, blocking setuid-based privilege escalation. | Cannot be disabled or configured with `security_opt`; that field is rejected. |
| **No host namespaces or devices** | Containers get their own IPC and PID namespaces. | `ipc` accepts `private` or `none` only; `pid`, `devices`, and `privileged` are rejected. GPUs are exposed through `runtime: nvidia` and `gpus`. |
| **Read-only root filesystem** | `read_only: true`. | Set `read_only: false`, or mount writable scratch space with `tmpfs` / `volumes`. |
| **Process limit** | `pids_limit: 65536`, a backstop against fork bombs. | Set an explicit `pids_limit` (`-1` for unlimited). |
| **Attested config mount** | `/tinfoil` is mounted read-only, exposing the verified config and attestation so clients can audit what's running. | Not configurable. |

> [!NOTE]
>
> If your app needs writable scratch space, add a `tmpfs` mount or set `read_only: false`. List required capabilities (for example `IPC_LOCK` for pinned memory or `NET_BIND_SERVICE` to listen below port 1024) under `cap_add`.
>
> A container with `cvm_admin: true` is exempt from these defaults: it runs privileged, as root, with a writable root filesystem. See [Direct admin SSH](https://docs.tinfoil.sh/containers/config-networking.md#direct-admin-ssh).

The read-only `/tinfoil` mount contains:

| Path | Contents |
| - | - |
| `/tinfoil/config.yml` | The verified `tinfoil-config.yml` this enclave booted with |
| `/tinfoil/attestation.json` | The enclave's attestation document |
| `/tinfoil/attestation.sock` | **Beta.** Unix socket for [fresh attestation requests](https://docs.tinfoil.sh/containers/attestation.md), when `attestation: true` |
| `/tinfoil/container-status.json` | Runtime status of the launched containers |
| `/tinfoil/mpk/mpk-<root_hash>` | [Model weights](https://docs.tinfoil.sh/containers/models.md) shared with every container, when no container lists them in `models` |
| `/tinfoil/models/<name>` | Model weights listed in this container's `models` |

## GPU security

Hopper GPUs, including H100 and H200, use unencrypted NVLink for communication between GPUs. The enclave refuses to boot with multiple Hopper GPUs unless the measured config explicitly allows this traffic. The check runs before secrets are retrieved or containers start.

Set the following top-level field in `tinfoil-config.yml` to opt in:

```yaml theme={"dark"}
gpus: 8
security:
  allow-unencrypted-nvlink: true
```

| Field | Type | Default | Description |
| - | - | - | - |
| `security.allow-unencrypted-nvlink` | bool | `false` | Allow multiple Hopper GPUs despite their unencrypted NVLink traffic. |

Omitting `security` or `allow-unencrypted-nvlink` leaves this permission disabled. Single-GPU Hopper enclaves and supported Blackwell configurations do not require it.

> [!WARNING]
>
> Enabling this setting accepts that data exchanged between Hopper GPUs over NVLink is not encrypted. GPU attestation remains required, and the setting does not disable CPU-to-GPU encryption. Because it is part of the measured config, changing it changes the configuration measurement that clients verify.

## Healthchecks

Add a `healthcheck` so the enclave checks that your app is ready before marking the instance **Running**. Without one in the config, the container is considered ready as soon as Docker starts the process (a `HEALTHCHECK` in the Dockerfile is not enough). That can be too early for apps that load model weights or warm caches before serving requests.

```yaml theme={"dark"}
containers:
  - name: "inference"
    image: "vllm/vllm-openai:v0.14.1@sha256:..."
    command: ["--port", "8001"]
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8001/health"]
      interval: 30s
      timeout: 5s
      start_period: 30m
```

| Field | Type | Description |
| - | - | - |
| `test` | list | Command to run inside the container. Prefix with `CMD` to exec directly, or `CMD-SHELL` to run through a shell. Exit code 0 = pass, non-zero = fail. |
| `interval` | duration | How often to run the check (e.g. `30s`). Docker default: 30s. |
| `timeout` | duration | How long a single check can take before it's counted as a failure (e.g. `5s`). Docker default: 30s. |
| `retries` | integer | Consecutive failures after `start_period` before the container is marked unhealthy. Docker default: 3. |
| `start_period` | duration | Grace period after container start during which failures don't count toward `retries` (e.g. `30m`). Docker default: 0s. |

**How it's used during boot.** Boot waits until Docker reports the container `Healthy`. If Docker reports `Unhealthy` (i.e. `retries` consecutive failures after `start_period` has elapsed), the deploy fails and the last healthcheck output is shown as the error detail.

The test command runs *inside* the container, so whatever you invoke (`curl`, `wget`, a language runtime) has to be available in the image. For an inference server like vLLM that already exposes `/health`, a `curl -sf http://localhost:<port>/health` check is idiomatic.

> [!TIP]
>
> If your container takes 15 minutes to load model weights, set `start_period` to at least 20 minutes. Otherwise, healthcheck failures during startup can exhaust `retries` and fail the deployment before the app is ready.

**See also.** The fields above follow Docker Compose semantics; the [Compose healthcheck reference](https://docs.docker.com/reference/compose-file/services/#healthcheck) covers exit codes and `CMD-SHELL` vs `CMD`. Only the five fields above are accepted. `disable: true` is rejected, and `test: ["NONE"]` must not be used: it turns off health reporting, so boot waits forever.

## Restart policy

By default, Docker does not restart a container when its process exits. For long-running servers, set `restart` so Docker restarts the process after a crash.

```yaml theme={"dark"}
containers:
  - name: "inference"
    image: "vllm/vllm-openai:v0.14.1@sha256:..."
    restart: always
```

| Value | Behavior |
| - | - |
| `no` | Don't restart. This is the default when `restart` is omitted. |
| `always` | Restart the container regardless of exit status. |
| `on-failure` | Restart only if the process exits with a non-zero status. |
| `unless-stopped` | Like `always`, but don't restart if the container was stopped explicitly. |

**Interaction with healthchecks.** The restart policy fires when the container **process exits**. It has no effect when Docker marks the container `Unhealthy` (the process keeps running; only its health state changes). During boot, the enclave fails the deployment on `Unhealthy` regardless of `restart`. Once the container has been declared `Healthy`, `restart` governs what happens if the process later dies.

**See also.** This field follows Docker Compose semantics, documented in the [Compose restart reference](https://docs.docker.com/reference/compose-file/services/#restart).


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