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

# Resource limits & quotas

> Understand the resource limits and naming constraints for Tinfoil Containers.

## Infrastructure tiers

Every organization and personal account has an infrastructure tier. The tier limits how many containers and bunkers can run at once and how much storage their volumes can use:

| Tier | Containers | Bunkers | Storage |
| :- | :- | :- | :- |
| Tier 1 | 5 | 5 | 32 GB |
| Tier 2 | 25 | 25 | 512 GB |
| Tier 3 | 50 | 50 | 2 TB |

Every account is on at least Tier 1. The tier rises automatically with your lifetime paid total, which counts paid API usage invoices, paid credit purchases, and paid infrastructure invoices. Organizations with GPU access for containers are on Tier 3. Tinfoil can also raise an account's limits.

To see your tier, limits, current usage, and the paid total each tier requires, open **Limits** in the dashboard under **Organization** (or **Account** for a personal account), then select **Containers** or **Bunkers**. Personal accounts have no **Containers** tab because only organizations run containers.

> [!NOTE]
>
> Need more than Tier 3 allows? [Contact us](mailto:contact@tinfoil.sh) to discuss your requirements.

### What counts toward the limits

* **Containers and bunkers** are counted separately. A container or bunker counts unless it is Stopped or Failed, so deploying a Stopped or Failed container, or starting a stopped or failed bunker, counts against the limit again. The Perimeter that your bunkers connect through counts toward neither limit.
* **Storage** is one pool shared by container volumes and bunker workspaces. Every volume counts at its full size until it is deleted, including detached volumes and the workspaces of deleted bunkers.

Storage sizes use decimal units: 1 GB is 1,000,000,000 bytes and 1 TB is 1,000 GB.

### Bunker workspaces

Each bunker stores its files on a workspace volume. Choose its size when you create the bunker: 2, 4, 8, 16, 32, or 64 GB, with 16 GB as the default. Use the **Workspace size** selector in the dashboard, the `--workspace-size` flag of `tinfoil bunker create`, or the `workspace_size_gb` field of an API create request. A workspace can't be resized after creation, and reusing an existing workspace (`--workspace`) keeps its size. To create a workspace volume ahead of time, run `tinfoil volume create NAME --bunker --size 16GB`.

Bunkers must be enabled for your organization or personal account. [Contact us](mailto:contact@tinfoil.sh) to request access.

### When you reach a limit

A request that would go over a limit fails with an error message that explains how to free capacity or get a higher limit. The dashboard links to the matching **Limits** tab, and the CLI points to your account limits.

| HTTP status | Code | When |
| :- | :- | :- |
| `409` | `CONTAINER_LIMIT_REACHED` | Creating or deploying a container when the container limit is already reached |
| `409` | `SANDBOX_LIMIT_REACHED` | Creating or starting a bunker when the bunker limit is already reached |
| `409` | `STORAGE_LIMIT_EXCEEDED` | Creating a volume or bunker workspace that does not fit in the free storage |
| `400` | `INVALID_WORKSPACE_SIZE` | Choosing a workspace size other than 2, 4, 8, 16, 32, or 64 GB |

To free capacity, stop or delete containers and bunkers you no longer need, and delete unused volumes.

## Resource options

Each container specifies its CPU, memory, and GPU requirements in
`tinfoil-config.yml`. These values are measured and published with the release;
create, deploy, and update requests cannot override them. Available options:

> [card] CPU
>
> | Cores | Config value |
> | :- | :- |
> | 2 | `cpus: 2` |
> | 4 | `cpus: 4` |
> | 8 | `cpus: 8` |
> | 16 | `cpus: 16` |
> | 32 | `cpus: 32` |

> [card] Memory
>
> | RAM | Config value |
> | :- | :- |
> | 8 GB | `memory: 8192` |
> | 16 GB | `memory: 16384` |
> | 32 GB | `memory: 32768` |
> | 64 GB | `memory: 65536` |
> | 128 GB | `memory: 131072` |
> | 256 GB | `memory: 262144` |
> | 512 GB | `memory: 524288` |

Public resource shapes are CPU-only, `gpus: 1`, or `gpus: 8`. GPU access must be enabled for your organization.

> [!TIP]
>
> Start with the smallest size that works for your workload and scale up if you see high CPU utilization or slow response times. Over-provisioning wastes resources and you can always resize by updating to a release with a changed `tinfoil-config.yml`.

## Choosing the right size

Pick resources based on what your application actually needs, not what you think it might need. A few rules of thumb:

* **Compiled languages** (Go, Rust, C++) are memory-efficient; 8 GB is often enough.
* **Interpreted runtimes** (Python, Node.js, Ruby) typically need 16 GB+ for production workloads.
* **CPU cores should match your concurrency model.** A single-threaded app won't benefit from 32 cores. A multi-process web server (e.g. Gunicorn with workers) should have roughly one core per worker.
* **Measure first.** Run your app locally with resource limits to understand its actual footprint before deploying.


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