Letting Docker through your firewall

Does this apply to me?

Only if you turned on Allow this container to manage Docker containers for a project, and you are on Linux with a firewall enabled. Everything else in Borago Board works without any of this.

The symptom

Tasks run normally, the container starts, git works, the AI writes code - but anything involving Docker quietly fails. The AI reports that Docker is unavailable, or that a container "needs to be run on a host with real Docker access", and no new containers appear in the project's container list.

Why it happens

Your project's container does not get the Docker socket. That would be handing it root on your machine: anything with the raw socket can start a privileged container that mounts your whole filesystem. Instead, Borago Board runs a policy proxy - a small gatekeeper that inspects every Docker request, forces containers the AI creates into a sandboxed runtime, labels them so they can be tracked and cleaned up, and rejects the requests that would break out of the sandbox.

That proxy listens on your machine, and the container connects to it across the Docker bridge network. On Linux that connection is inbound traffic to your host, which lands in the firewall's INPUT chain. Docker writes its own rules for traffic it routes (containers reaching the internet, published ports) but never touches INPUT - that chain belongs to you. So ufw and firewalld drop the connection by default, and because everything else in Borago Board uses a different path, nothing else breaks. That is what makes this so confusing to run into.

The fix

In the app: open the project's settings, go to the Containers tab, and use Allow through firewall in the "Docker container management" panel. It detects which firewall you use, shows the exact rule, and asks for your password through your desktop's standard prompt. That is the whole fix - the rest of this page is for people who would rather run it themselves or need to hand it to whoever administers the machine.

You can press that button from the web or mobile board too, if your desktop app is running - the rule is applied on the machine that has the firewall, so the prompt still appears there and only you, at that machine, can approve it. Nothing about this can be granted remotely.

If your system has no PolicyKit agent to show that prompt - common on a tiling window manager or a minimal install - Borago Board opens your terminal with the command ready instead, and you type your password there. If it cannot find a terminal either, it shows the command with a Copy button. Either way you see the exact command before it runs, and after it has run.

The rule is scoped to one port. Each project gets its own port, held for as long as container management stays on, so the rule does not need revisiting. Replace 45703 below with the port shown in the Containers tab, and docker0 with the interface shown next to it if yours differs.

ufw (Ubuntu, Debian, Pop!_OS)

sudo ufw allow in on docker0 to 172.17.0.1 port 45703 proto tcp

To undo it later, repeat the command with delete after ufw.

firewalld (Fedora, RHEL, CentOS, openSUSE)

sudo firewall-cmd --permanent --zone=docker --add-port=45703/tcp
sudo firewall-cmd --reload

If Docker has not put your bridge in the docker zone yet, add --add-interface=docker0 to the first command. To undo, swap --add-port for --remove-port and reload again.

nftables

sudo nft add rule inet filter input iifname "docker0" tcp dport 45703 accept comment "borago-proxy-45703"

Check your table and chain names first with sudo nft list ruleset - the names above are the common defaults, not a guarantee.

The comment is what makes the rule removable later. nftables deletes rules by handle rather than by restating them, so Borago Board finds the handle by looking up that exact comment, and removes only the first rule carrying it. If nothing matches - because the rule was edited by hand or added another way - nothing is deleted and you get an error rather than a guess. Keep the comment if you run the command yourself and you keep the in-app Remove button working.

To remove it by hand instead:

sudo nft -a list chain inet filter input | grep borago-proxy-45703
sudo nft delete rule inet filter input handle <N>

Plain iptables

sudo iptables -I INPUT -i docker0 -p tcp --dport 45703 -j ACCEPT

This does not survive a reboot on its own - save it with your distribution's iptables-persistent equivalent.

Checking it worked

Back in the Containers tab, press Re-check. Borago Board does not read your firewall's configuration - that needs root, and asking for your password just to look would be worse than the problem. Instead it dials the proxy from inside your project's container, which answers the only question that matters: can the AI use Docker. You do not need to restart anything.

To check by hand, from a terminal (using your project's port):

docker run --rm --network bridge alpine sh -c 'nc -zv -w3 172.17.0.1 45703'

A timeout means the traffic is being dropped - that is this problem. A connection refused means it reached your host and nothing was listening, so the firewall is fine and Borago Board is simply not running.

Is this safe?

The rule allows one TCP port, on the Docker bridge interface only, reachable only by containers on that bridge - not from your network and not from the internet. It is considerably narrower than the advice you will find elsewhere for this class of problem (ufw allow in on docker0), which opens every port on your machine to every container you run.

What is behind the port is the policy proxy, not the Docker socket. Containers the AI creates are forced into a sandboxed runtime where the host supports it, labelled as belonging to that project, and confined to that project's own containers. Requests for privileged mode, host networking, added capabilities or bind mounts from your filesystem are rejected before they reach Docker.

If you would rather not grant it at all, turn off Allow this container to manage Docker containers for the project. Every other feature keeps working; the AI simply cannot create containers.