A project's container in Borago Board never gets the Docker socket, because on Linux a container that can create containers is effectively root on the host. When a task needs a database, the agent asks a policy proxy instead. This tutorial turns that on for one project and has the agent run Postgres beside it for the tests.

You will build

A project whose agent can start containers. A Postgres container running as a sibling of the project container, listed with the project's containers. A passing test run against it.

You need

The desktop app with a project whose container the app manages, see Creating a project. The project's code should have database migrations and tests, or the task can create them.
On Linux, gVisor installed, see Installing Docker with the app. Without it the agent's containers are restricted but not sandboxed, and the Containers tab says so.

Steps

1. Turn on container management

Press Edit project and open the Containers tab. Check that Dev container name is on Auto-generated, since a custom container is not offered this setting. Tick Allow this container to manage Docker containers. Read the warning that this widens the trust boundary, then press Save changes.

What happens. The app installs the Docker client into the running container in the background. A notification titled Docker client installed says when it is ready, with no rebuild needed. Let other devices reach containers the AI creates stays off, so any port the agent publishes is bound to this computer only.

2. Allow the proxy through the firewall on Linux

Open Edit project and the Containers tab again. The panel Docker container management tests the path from the container to the proxy. When it reads Reachable from the container, go on. When it reads Blocked - the AI cannot create containers, press Allow through firewall and approve the single administrator prompt.

What happens. The rule allows one port, and the app shows the exact command before it runs. On macOS and Windows no rule is needed and the panel does not appear. The full explanation and the manual commands are on Letting Docker through your firewall. From a browser or a phone the button works while the desktop app is connected, but the prompt still appears on the desktop, so someone must be at it.

3. Know what the agent may and may not do

The agent may pull images, create, run, stop and remove containers, create volumes and networks, exec into its containers and use compose. Every container it creates runs under gVisor where installed and is marked as the project's.

The proxy refuses privileged containers, host folder mounts, host networking and added capabilities, and every prune. It refuses any container, volume or network that belongs to another project. A port published on an address other than this computer is refused unless you allowed it in step 1.

4. Write the task

Press Add task in Planning and paste this, adjusted to your stack:

Start a Postgres 17 container for this project as a sibling container,
named after the project with a "-postgres" suffix, with a named volume for
its data. Do not install Postgres inside this container.
Wait until it accepts connections, checking with pg_isready inside it.
Reach it over this container's network by its IP address, looked up with
docker inspect, and pass the connection string to the app through the
DATABASE_URL environment variable. Do not commit the connection string.
Run the database migrations, then the full test suite against it.
Leave the Postgres container running and report the command you used to
start it.

Press Add task and drag the card to To Do.

What happens. A container the run creates is a sibling on your machine, never nested inside the project container. The sibling is placed on the project's own network, and the agent reaches it by its address there. If the proxy cannot be reached, the queue holds the task before it starts, with Auto-run paused - allow Docker access through the firewall.

5. See the sibling container

Press Containers among the project controls. The list headed Containers - and the project's name shows the project container first, then the Postgres container, each with its state and start, stop and restart buttons. From now on the board's start and stop ask whether to act on Start all containers or Start only the dev container, and the same for stop.

6. Stop it or remove it

Stop Postgres from its row in the list, or with Stop all containers. The app never removes an agent's container on a stop. To remove it and its data, ask in a task:

Remove this project's Postgres container and its data volume.

Check it worked

The task summary reports the migrations and a passing test run, and the containers list shows Postgres running.

What a project delete does

Deleting the project moves it to the recycle bin and stops every container in its family, so a restore finds them intact. Destroying it from the bin, or the bin's expiry after 30 days, removes the family's containers. The Postgres image stays, because a pulled image is shared. A volume the agent created may stay too. Settings, then Docker, then Docker disk usage shows the totals, and such a volume is counted there without a name. See Recovering things.

Where to go next

A frontend and a backend as connected projects lets another project reach this one.

Source as Markdown: /docs/tutorials/postgres-beside-the-project.md · Updated 2026-10-11 · Was this right? Tell us

Let the agent run Postgres beside the project