# Why Docker

Why Borago Board runs every task in a Docker container, what that buys you, what it costs, and what the app does to make it a one-time button.


Borago Board needs Docker on every platform. Nothing runs without it, by design. This page says why, in enough detail to decide whether that suits you.

## What the container buys you

**A wall between the agent and your computer.** The agent runs shell commands, installs packages, edits files and runs tests. Inside a container it does that to one project, on the project's own private network, with one folder of yours mounted in and nothing else of yours in reach. A project created on an older version keeps Docker's shared network until its container is next recreated. It cannot see your home directory, your browser profile, your keychain or your other projects, unless you connect two projects on purpose. On Linux with gVisor installed, the container additionally runs under it, a user-space kernel that stands between the container and the real one. On macOS and Windows, Docker Desktop's virtual machine is that wall.

**A machine per project that you can rebuild.** Each project gets a generated Dockerfile and compose file. When the agent installs a tool, the app adds it to the Dockerfile so it survives a rebuild, as a line the next build tries, and takes it out again if that build fails. When the install cannot be rewritten for build time, the commands are handed to you in an action comment instead. When a container is broken, rebuild it. The base image is a control, so a project can move from one Ubuntu release to the next in a click. A project can even be pinned to another CPU architecture and run emulated, without gVisor.

**A shell you can open.** The terminal button on the board opens a shell inside the container, in tabs, from the desktop and from a phone while the desktop is online. Scripts run there too. What the agent did is where you can look at it.

**Reproducibility.** The same Dockerfile builds the same environment on any machine, and a project created in the browser or on the phone gets its Docker files written by the desktop when it next syncs there, and its container built at its first start.

**Sibling services under a policy.** With container management on, the agent can start a database beside the project. It reaches Docker only through a policy proxy that permits the containers the agent created on the project's own network and refuses everything else, so the agent cannot mount your disk or reach a project you have not connected. A project created on an older version keeps Docker's shared network until its container is recreated or it is moved from Settings, then Docker.

## What it costs

- A one-time install of Docker, and on Linux of gVisor with it. The app does this for you behind one administrator prompt on Linux, and downloads, verifies and opens the official Docker Desktop installer on macOS and Windows. See [what the app sets up for you](/setup/).
- Disk space for images. The app removes the image it replaced on every rebuild and shows disk usage with safe cleanup under Settings, then Docker.
- Memory. Each container carries a cap derived from your machine's RAM so a runaway build cannot take the host down, and the cap is a control.
- On Linux the docker group or socket access. The app grants it without a log-out.
- On a Mac, Docker Desktop's virtual machine uses a slice of RAM whenever it runs.

## What runs without Docker

Nothing. The board opens, and the banner offers to set Docker up. The decision was to have one execution model rather than a safe one and an unsafe one, so that "the agent ran a command" always means "inside a container".

## Common worries, answered

| Worry | Answer |
|---|---|
| I do not know Docker | You do not need to. Every setting is a control in the app, the files are generated, and the terminal is a button. |
| Docker Desktop needs a licence at work | Docker Desktop's terms are Docker's, and the app leaves the licence decision to its installer. On Linux the app installs the distribution's own Docker packages, which need no Docker Desktop. |
| It will slow my machine | A container is a process on Linux. On macOS and Windows the virtual machine has a cost while it runs. gVisor adds a small overhead to system calls. |
| I already have Docker | The app finds it, including in the places a Finder-launched app cannot see, and tells running, stopped and unreachable apart. |
| My firewall blocks it | The one rule the policy proxy needs is added behind one prompt. Other firewalls have the manual commands on [letting Docker through your firewall](/docs/firewall/). |

Related: [What the app sets up for you](/setup/), [Security](/security/), [Installing Docker with the app](/docs/guides/installing-docker/), [Containers](/docs/reference/containers/).