# Storage for AI Teams

How your organization's storage is shared by its AI Teams, how a team's disk grows, and how owners and admins set a cap or a reserve for each AI Team.



<Callout title="Rolling out.">
  Pooled storage is reaching organizations over the coming weeks. Until it reaches yours, each AI
  Team grows up to an even share of your organization's storage, and the Storage tab in Billing is
  not shown yet.
</Callout>

## One pool for the whole organization [#one-pool-for-the-whole-organization]

Your plan includes an amount of storage for the whole organization. Each extra AI Team you buy
adds its share, and each storage block adds 100 GB. All of it is one pool that your AI Teams share.

Every AI Team has its own disk. A new AI Team starts with a small disk, and the disk grows on its
own, 10 GB at a time, when it is about 85% full. It can grow into any part of the pool that no
other AI Team is using or has reserved. A storage block can be used in full by a single AI Team.

A disk never shrinks and nothing on it is ever removed to make room. A stopped or sleeping AI Team
keeps its disk, and that space stays counted as used, so another AI Team can never grow into it.

## When the pool is full [#when-the-pool-is-full]

When the AI Teams' disks use the whole pool:

* A team's disk stops growing. Its data is safe and nothing is removed. Team Settings, under
  **Storage**, says **Growth paused** and why.
* A new AI Team cannot be created, because there is no room for its first disk. You are asked to
  add storage first.

To make room, add a 100 GB storage block in **Billing**, under **Plan & add-ons**, or lower a
reserve (see below). An owner or admin sees an **Add 100 GB** button on the team's Storage section
when the pool is the reason a team cannot grow.

## When a disk is almost full [#when-a-disk-is-almost-full]

HQ warns you before an AI Team's disk fills up, in the same places it warns about a busy processor
or low memory: the **Cloud Computer** pill at the top of a session, and the card on the AI Team's
overview and **Settings**. The pill shows **Disk** and a percentage; open it to read the warning.

The percentage counts the room the disk can still grow into. A disk that is 85% full today but can
still grow a lot does not warn, because it grows by itself. The warning comes as the disk gets close
to the most it can grow to: its cap, your trial or plan allowance, or what is left in the pool. If a
disk fills faster than it can grow, it warns too.

It warns at:

| Disk full | What it means                                       |
| --------- | --------------------------------------------------- |
| 85%       | Time to make room.                                  |
| 90%       | Make room soon: see below for what happens at 100%. |
| 95%       | The disk is about to run out of space.              |

What 100% means:

* Part of every disk (5%) is kept for the system, so 100% is when your files can no longer be
  saved.
* If the AI Team uses Docker, 100% comes earlier: Docker is stopped when only about 1 GB or 3% of
  the disk is left, whichever is more, and that restarts the Cloud Computer and ends every running
  session. The percentage already counts this, so 95% always comes before Docker is stopped.

A warning goes away once the disk is 5 points below the line, so it does not come and go while
you clean up.

To make room:

* Delete files you no longer need from the AI Team's folder.
* Clear `/tmp`. Each session's `/tmp` is on the team's disk.
* Remove Docker images and containers you no longer use (for example, `docker image prune`).

Or get more space. The warning names the fix that applies:

* When a cap stops the disk, someone who can change storage limits raises the AI Team's cap under
  **Settings**, **Storage**.
* During a trial, an owner or admin starts the paid plan in **Billing**; storage can be added after
  that.
* When the pool or the plan allowance is full, an owner or admin adds storage in **Billing**.
* With unlimited storage there is nothing to add; making room is the fix.

Everyone else sees a note to ask an organization owner or admin.

## Caps and reserves [#caps-and-reserves]

Organization owners and admins can set two limits on any AI Team, from the team's **Settings**,
under **Storage**, or from **Billing**, under **Storage**, with **Edit**:

* **Cap**: the AI Team never grows past this size. The smallest cap is 10 GB. A cap below the
  current disk does not shrink it and removes no data. It only stops the disk from growing.
* **Reserve**: storage held for this AI Team. Other AI Teams cannot grow into it, even while this
  team's disk is smaller. A reserve cannot be more than the cap, and you can only reserve space the
  pool still has free.

Leave a field empty for no cap or no reserve. Every change is recorded in the activity log.

The **Storage** tab in **Billing** shows the pool (disks, reserved and free space) and, for each
AI Team, its disk, cap, reserve, how far it can grow, and whether growth is paused.

## Who can see and change storage [#who-can-see-and-change-storage]

| Who                         | Sees                                      | Can change caps and reserves |
| --------------------------- | ----------------------------------------- | ---------------------------- |
| Organization owner or admin | Every AI Team's storage and the pool      | Yes                          |
| Organization member         | The storage of the AI Teams they can open | No                           |

Members see their AI Team's disk, how far it can grow, and its cap and reserve, but not the sizes
of other AI Teams.

## Trials and unlimited plans [#trials-and-unlimited-plans]

* **Trial**: an AI Team grows up to the 20 GB a trial includes. Caps and reserves can still be set.
* **Unlimited storage** (Enterprise): there is no pool to share. A cap can still be set on any AI
  Team; a reserve does not apply.

## What is kept when the Cloud Computer restarts [#what-is-kept-when-the-cloud-computer-restarts]

The AI Team's disk is kept: the team's folder, and your home folder, `$HOME`, with everything you
install or save in it. The rest of the Cloud Computer comes fresh from the system image every time it
restarts (Update, Restart or wake from sleep).

So install your own tools into `$HOME`, for example a program in `$HOME/.local/bin`, and keep
sign-in tokens and settings under `$HOME/.config`. The folder `/home/node` belongs to the system
image and is read-only: saving a tool there fails right away with "Permission denied", instead of
seeming to work and disappearing at the next restart.

Some tools come with every Cloud Computer, so there is nothing to install or keep for them: `git`,
`python3`, `curl`, `jq`, ImageMagick, `ripgrep`, `ffmpeg` (with `ffprobe`) and `unzip`.

For a Node tool, this works on every Cloud Computer. The first line puts `$HOME/.local/bin` on your
`PATH` for every future session, once:

```sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"
npm install -g --prefix "$HOME/.local" <package>
```

## Units [#units]

Storage is counted in GB of 1024 MB each, the same unit used everywhere else in HQ.
