Docker in a team

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 team's machine starts. Press Restart now to apply on the Docker card, or Restart machine in the team's Machine settings, to apply it straight away. Running sessions pause while the machine 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

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

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 machine restarts. See Storage.
• Containers stop when the machine restarts or updates. Images and volumes are kept.
• A team machine that goes idle keeps its containers paused and resumes them intact. Running containers do not keep a machine awake.

Supabase

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

npx supabase init
npx supabase start

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

Docker's storage starts small and grows when the team's machine restarts, never while it runs. If Docker says no space left on device:

1. An organization owner or admin presses Restart machine on the team's Docker card, or in the Machine section of the team's Settings. Running sessions pause while the machine restarts and come back where they were.
2. Run the command again. The first big pull, like a Supabase stack, may need one or two restarts.

When Docker could not start because it ran out of storage, the Docker card says "Docker ran out of storage. Restart the machine 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

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. Connect to it from a tool on this computer with hq forward or the VS Code extension.

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

hq forward 54321
hq forward 54323

Then open http://localhost:54323 for Studio. See Port forwarding for the options.

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

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:

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

Good to know

• Containers you run with extra privileges can read or change this machine'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 agent, 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 machine they are separated by Linux namespaces, not by separate user ids.