3.8 Docker Browser Configuration

When deploying Flocks with Docker on macOS or Windows, you can let Flocks inside the container connect to Google Chrome on the host. Chrome provides the CDP (Chrome DevTools Protocol) service, and Flocks controls the browser through that service.

3.8.1 Start Chrome on a macOS Host

Run this on the macOS host:

open -na "Google Chrome" --args \
  --remote-debugging-port=19122 \
  --remote-debugging-address=0.0.0.0 \
  --user-data-dir="$HOME/.flocks/browser/chrome-debug"

This command starts Chrome with an independent user data directory to avoid conflicts with your daily Chrome instance.

Run the following command to verify the CDP service:

curl http://127.0.0.1:19122/json/version

If the returned JSON contains webSocketDebuggerUrl, Chrome has started successfully.

3.8.2 Start Chrome on a Windows Host

Run this in Windows PowerShell:

$chrome = "$env:ProgramFiles\Google\Chrome\Application\chrome.exe"
Start-Process -FilePath $chrome -ArgumentList @(
  "--remote-debugging-port=19122",
  "--remote-debugging-address=0.0.0.0",
  "--user-data-dir=$env:USERPROFILE\.flocks\browser\chrome-debug"
)

If Chrome is not installed in the default path, change $chrome to the actual chrome.exe path. This command also uses an independent user data directory and does not reuse the configuration of your daily Chrome instance.

Run the following command to verify the CDP service:

curl.exe http://127.0.0.1:19122/json/version

If the returned JSON contains webSocketDebuggerUrl, Chrome has started successfully. Windows Firewall also needs to allow Docker Desktop's virtual network to access port 19122 on the host.

3.8.3 Start the Flocks Container

When starting the container, map the unified Flocks service port:

macOS:

docker run -d \
  --name flocks \
  -e TZ=Asia/Shanghai \
  -e BU_CDP_URL="http://host.docker.internal:19122" \
  -p 5173:5173 \
  --shm-size 4gb \
  -v "${HOME}/.flocks:/home/flocks/.flocks" \
  ghcr.io/agentflocks/flocks:latest

Windows PowerShell:

docker run -d `
  --name flocks `
  -e TZ=Asia/Shanghai `
  -e BU_CDP_URL="http://host.docker.internal:19122" `
  -p 5173:5173 `
  --shm-size 4gb `
  -v "${env:USERPROFILE}\.flocks:/home/flocks/.flocks" `
  ghcr.io/agentflocks/flocks:latest

The WebUI and API are both served on port 5173, with API requests routed through the same-origin /api endpoint. BU_CDP_URL is injected when the container starts, allowing Flocks to connect directly to Chrome on the host. Chrome runs on the host, and the container actively connects to host port 19122, so you do not need to publish that port to the host with -p 19122:19122.

3.8.4 Configure the Browser in Flocks

Enter the Flocks container:

docker exec -it flocks bash

For first-time configuration, run the following inside the container:

Do not redirect the entire Flocks data directory with FLOCKS_ROOT=/tmp/.flocks. This also affects config, plugins, memory, and console login state, and all of that data will be lost after container recreation. The recommended approach is to link only ~/.flocks/browser to a temporary directory, while keeping other data in the persistent ~/.flocks mount.

macOS Docker Desktop:

mv ~/.flocks/browser /tmp/flocks-browser
ln -s /tmp/flocks-browser ~/.flocks/browser
export BU_CDP_URL="http://host.docker.internal:19122"
flocks browser --setup

Windows Docker Desktop:

mv ~/.flocks/browser /tmp/flocks-browser
ln -s /tmp/flocks-browser ~/.flocks/browser
export BU_CDP_URL="http://host.docker.internal:19122"
flocks browser --setup

host.docker.internal is the host domain provided by Docker Desktop for accessing host services from macOS or Windows containers. There is no need to write a specific IP address in the documentation or configuration.

The symlink is stored in the persistent ~/.flocks directory and redirects only the browser runtime directory to /tmp/flocks-browser. It does not change the location of other Flocks data. After configuration, Flocks connects to Chrome on the host through BU_CDP_URL.

If you delete and recreate the container, the symlink remains in the persistent directory, but the temporary directory is cleared. After entering the new container, run the following commands to restore the browser runtime directory:

mkdir -p /tmp/flocks-browser
flocks browser --setup

Do not expose port 19122 to untrusted networks. Otherwise, other devices may control the browser through CDP.