Connecting to Docker Daemon from inside a Tart VM

com.scribular.host-docker-proxy.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.scribular.host-docker-proxy</string>

  <key>ProgramArguments</key>
  <array>
    <string>/bin/zsh</string>
    <string>-lc</string>
    <string>~/docker-host-proxy.sh</string>
  </array>

  <key>EnvironmentVariables</key>
  <dict>
    <key>HOST_IP</key>
    <string>192.168.110.1</string>
    <key>PORT</key>
    <string>2375</string>
    <key>DOCKER_SOCK</key>
    <string>/var/run/docker.sock</string>
  </dict>

  <key>RunAtLoad</key>
  <true/>

  <key>KeepAlive</key>
  <true/>

  <key>StandardOutPath</key>
  <string>/tmp/host-docker-proxy.log</string>

  <key>StandardErrorPath</key>
  <string>/tmp/host-docker-proxy.log</string>
</dict>
</plist>

docker-host-proxy.sh

#!/bin/zsh

set -euo pipefail

HOST_IP="${HOST_IP:-192.168.110.1}"
PORT="${PORT:-2375}"
DOCKER_SOCK="${DOCKER_SOCK:-/var/run/docker.sock}"

SOCAT_BIN="$(command -v socat || true)"
if [[ -z "${SOCAT_BIN}" ]]; then
  echo "socat not found in PATH"
  exit 1
fi

if [[ ! -S "${DOCKER_SOCK}" ]]; then
  echo "Docker socket not found: ${DOCKER_SOCK}"
  exit 1
fi

exec "${SOCAT_BIN}" \
  "TCP-LISTEN:${PORT},bind=${HOST_IP},reuseaddr,fork" \
  "UNIX-CONNECT:${DOCKER_SOCK}"

docker-in-tartelet-vm.md

Docker In Tartelet VM

⚠️ this PR needs merging before this will work. Until then, your agent can patch your local copy using the diff: redwoodjs/agent-ci#161

This note documents the current working method for using Docker from the Tart VM by forwarding the host Mac's Docker socket over a Tart-reachable TCP listener.

Summary

The Tart VM is a separate macOS guest. It is not inside Docker Desktop's managed Linux VM, so Docker's /var/run/docker.sock.raw guidance for Docker Desktop extensions does not apply directly here.

The working setup is:

1. Run socat on the host Mac.
2. Bind it to the Tart-facing host IP: 192.168.110.1.
3. Forward that TCP listener to the host's Docker socket at /var/run/docker.sock.
4. Point the VM Docker client at tcp://192.168.110.1:2375.

Security Model

This method exposes host Docker access to anything in the VM that can reach 192.168.110.1:2375.

That means:

• it is convenient
• it is not tightly scoped
• it should be treated as high-privilege host access through Docker

It is acceptable here because it is simple and working, but it is not equivalent to a least-privilege design.

Host Requirements

On the host Mac:

• Docker Desktop is installed and running.
• docker ps works on the host.
• socat is installed.
• /var/run/docker.sock exists.

Checks:

docker ps
ls -l /var/run/docker.sock
which socat

If socat is missing:

brew install socat

Host Artifacts

These files now exist in this repo:

• Script: docker-host-proxy.sh
• LaunchAgent: com.scribular.host-docker-proxy.plist

The installed host copy of the script should live at:

• ~/docker-host-proxy.sh

docker-host-proxy.sh

Purpose:

• verifies socat exists
• verifies /var/run/docker.sock exists
• starts the TCP-to-Unix proxy on 192.168.110.1:2375

Current behavior:

socat TCP-LISTEN:2375,bind=192.168.110.1,reuseaddr,fork UNIX-CONNECT:/var/run/docker.sock

com.scribular.host-docker-proxy.plist

Purpose:

• starts the host proxy at login
• keeps it running
• logs output to /tmp/host-docker-proxy.log

Host Installation

Make sure the script is executable:

cp ./docker-host-proxy.sh ~/docker-host-proxy.sh
chmod +x ~/docker-host-proxy.sh

Install the LaunchAgent:

cp ./com.scribular.host-docker-proxy.plist ~/Library/LaunchAgents/
launchctl unload ~/Library/LaunchAgents/com.scribular.host-docker-proxy.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.scribular.host-docker-proxy.plist

Verify it is running:

launchctl list | grep host-docker-proxy
lsof -iTCP:2375 -sTCP:LISTEN -n -P
tail -f /tmp/host-docker-proxy.log

Expected listener:

192.168.110.1:2375

Host Manual Run

If you want to run it manually instead of using launchd:

socat TCP-LISTEN:2375,bind=192.168.110.1,reuseaddr,fork UNIX-CONNECT:/var/run/docker.sock

VM Requirements

Inside the Tart VM:

• Homebrew is installed.
• Docker CLI is installed.
• The VM can reach the host at 192.168.110.1.

Install Docker CLI if needed:

brew install docker

VM Docker Client Setup

Point the VM Docker client at the host proxy:

export DOCKER_HOST=tcp://192.168.110.1:2375

If you want a named Docker context:

docker context create host-mac --docker "host=tcp://192.168.110.1:2375"
docker context use host-mac

If an older host-mac context exists and should be replaced:

docker context use default
docker context rm host-mac
docker context create host-mac --docker "host=tcp://192.168.110.1:2375"
docker context use host-mac

VM Credential Helper Fix

The VM Docker client may fail to pull images if ~/.docker/config.json references Docker Desktop's credential helper:

docker-credential-desktop

Typical error:

docker: error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH

Inspect the current config:

cat ~/.docker/config.json

If it contains entries like these, remove them:

• "credsStore": "desktop"
• "credHelpers": { ... "desktop" ... }

Minimal safe VM config:

mkdir -p ~/.docker
printf '{}\n' > ~/.docker/config.json

Verification

Basic connectivity test from the VM:

docker version
docker ps

Full end-to-end test:

docker run --rm hello-world

If this works, the full flow is operational:

• VM Docker CLI
• TCP proxy over Tart network
• host Docker socket
• host Docker daemon
• image pull and container run

Troubleshooting

EOF from docker ps

Example:

error during connect: Get "http://192.168.110.1:2375/...": EOF

Usually means:

• the TCP listener accepted the connection
• but socat could not reach the Unix socket on the host

Check:

ls -l /var/run/docker.sock
docker ps
tail -f /tmp/host-docker-proxy.log

No such file or directory from socat

If you see errors pointing at:

/Users/dev/.docker/run/docker.sock

that path is wrong on this machine.

Use:

/var/run/docker.sock

Nothing Listening on 2375

Check:

launchctl list | grep host-docker-proxy
lsof -iTCP:2375 -sTCP:LISTEN -n -P

If needed, reload:

launchctl unload ~/Library/LaunchAgents/com.scribular.host-docker-proxy.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.scribular.host-docker-proxy.plist

Pull Fails With docker-credential-desktop

Reset the VM Docker config:

mkdir -p ~/.docker
printf '{}\n' > ~/.docker/config.json

Then retry:

docker run --rm hello-world

Related Files

• [docker-host-proxy.sh](/Volumes/My Shared Files/scribular/docker-host-proxy.sh)
• [com.scribular.host-docker-proxy.plist](/Volumes/My Shared Files/scribular/com.scribular.host-docker-proxy.plist)