AI Workforce OneHQDocs

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

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

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 Cloud Computer restarts. See 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

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

npx supabase init
npx supabase start
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.

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

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:

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

If Docker isn't 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 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

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