# Docker in a team

Run docker, docker compose and local stacks like Supabase inside a team's sessions, and reach them with Preview or hq forward.



## Turn it on [#turn-it-on]

Docker is off for every team until two things are true:

1. Support has turned Docker on for your organization. Contact support to ask; it is available to
   organizations on a paid plan.
2. An organization owner or admin turns it on for the team, in the team's **Settings**, under
   **Docker**. Turning it on asks you to confirm your password or authenticator code.

The change takes effect the next time the AI Team Cloud Computer starts. Press **Restart now to apply** on
the Docker card, or **Restart Cloud Computer** in the team's **AI Team Cloud Computer** settings, to apply it straight
away. Running sessions pause while the Cloud Computer restarts and come back where they were.

Members of the team can see whether Docker is on, but only an organization owner or admin can
change it.

## Use it [#use-it]

Every terminal in the team's sessions can run Docker, and so can Claude and Codex:

```bash
docker run --rm hello-world
docker compose up -d
```

* Keep files you mount into containers inside the team folder. Other folders are not visible to
  Docker.
* Docker's storage starts small, as part of the team's storage, and grows when the team's Cloud Computer
  restarts. See [Storage](#storage).
* Containers stop when the Cloud Computer restarts or updates. Images and volumes are kept.
* An AI Team Cloud Computer that goes idle keeps its containers paused and resumes them intact. Running
  containers do not keep a Cloud Computer awake.

## Supabase [#supabase]

Run the Supabase command line tool with `npx`, which needs nothing installed:

```bash
npx supabase init
npx supabase start
```

<Callout title="On a Standard Cloud Computer, the first start can fail its health check.">
  The services start cold, and `npx supabase start` can stop at a health check before they are
  ready. Run `npx supabase start --ignore-health-check`: they come up within about a minute.
</Callout>

If it keeps stopping at a health check, set `enabled = false` under `[analytics]` in
`supabase/config.toml`.

The first `supabase start` pulls several large images. If it says `no space left on device`, see
[Storage](#storage).

## Storage [#storage]

Docker can use up to 90 % of the team's storage from the start, and that limit grows with the
team's storage while the Cloud Computer runs. Docker's files count toward the team's storage only by what
they really take: deleting images or volumes, or running `docker system prune`, gives the space back
right away.

When the team's storage gets nearly full, it grows on its own, up to the plan's limit. At the limit,
Docker commands may say `no space left on device`, and if the storage stays nearly full Docker stops,
so git and sessions keep working. Free some space or add storage, then restart the Cloud Computer:

1. An organization owner or admin presses **Restart Cloud Computer** on the team's **Docker** card, or in
   the **AI Team Cloud Computer** section of the team's **Settings**. Running sessions pause while the Cloud Computer
   restarts and come back where they were.
2. Run the command again.

When Docker could not start because it ran out of storage, the Docker card says
"Docker ran out of storage. Restart the Cloud Computer to give Docker more room." and its button reads
**Restart now to apply**. It does the same restart. You can also free space with
`docker system prune`.

## Open a container's app or API [#open-a-containers-app-or-api]

**Preview**, in the session header, finds the ports your containers publish on its own, a few
seconds after they start, and names each one after its container and image, for example
`hello-web (nginx) · 4000`. Nothing has to be printed in the terminal. Open Supabase Studio (port
54323\) or the API (port 54321) from there.

A port that does not answer like a web page, such as a database, is listed under **Other ports**
instead. It doesn't count toward the number on the **Open preview** button, which counts only named
apps. Press **Open** on its row to try it in your browser anyway.

To use a port from a tool on this computer, forward it:

```bash
hq forward 54321
hq forward 54323
```

Then open `http://localhost:54323` for Studio. See [Port forwarding](/docs/cli/port-forwarding/)
for the options.

Ports 2375 and 2376 are the Docker API and can't be previewed or forwarded.

## Files a container created [#files-a-container-created]

A container that runs as root can create files in the team folder that your sessions cannot change
or delete. To take them back, run this in the folder that holds them:

```bash
docker run --rm -v "$PWD":/w alpine chown -R 1000:1000 /w
```

## If Docker isn't responding [#if-docker-isnt-responding]

HQ keeps checking Docker on the team's Cloud Computer. If Docker stops answering for about a minute, the
team's **Docker** card says **Docker isn't responding**. Sessions keep working, but `docker`
commands fail or hang.

An organization owner or admin presses **Restart Cloud Computer** on the Docker card to bring Docker
back. Sessions pause while the Cloud Computer restarts and come back where they were. Your images,
volumes and files are kept; running containers stop and need to be started again. HQ never restarts
the Cloud Computer by itself.

If Docker starts answering again on its own, the card goes back to **Docker is on**. If it keeps
happening after a restart, contact support.

Sometimes Docker keeps answering but can't start any container: `docker run` or `docker compose up`
fail with "function not implemented". The card then says **Docker needs a restart**. Only a restart of
the Cloud Computer fixes this, so press **Restart Cloud Computer** (an organization owner or admin).
Don't restart Docker from a terminal: it doesn't help and can make it worse.

## If Docker didn't start [#if-docker-didnt-start]

If a Cloud Computer can't load its latest settings when it starts, Docker only starts when HQ last
allowed it. Otherwise the Docker card says **Docker did not start** with "Docker stayed off because the
Cloud Computer couldn't load its latest settings when it started." Sessions keep working. An
organization owner or admin presses **Restart Cloud Computer** to try again.

## Good to know [#good-to-know]

* Containers you run with extra privileges can read or change this Cloud Computer's unencrypted network
  traffic, and can disconnect it until it restarts. Only run images you trust.
* On most teams, everyone shares one Docker: any member, and any session's AI Employee, can see and use the
  team's containers, images and volumes.
* On a team that keeps each member's work separate: Docker keeps each member's containers separate,
  but on one Cloud Computer they are separated by Linux namespaces, not by separate user ids.
  Each member has their own Docker, with their own containers, images and volumes. A teammate's
  `docker ps` doesn't show yours. Keep files you mount into containers inside the team folder: your
  home folder is not visible to Docker.
  Right after the Cloud Computer starts, each member's Docker takes about a minute to be ready. Sessions
  you start in that minute work without Docker, and the session says "This session started without
  Docker. Restart it to get Docker." Once Docker is ready, press **Restart** on that notice. If you have
  other sessions open, stop them first: a session gets Docker only once none of yours is still running
  without it.
