Docker Linux Workspace

FerrisGrid can run inside a Linux container with its own X11 display. The agent calls FerrisGrid from your host terminal with docker exec, while mouse and keyboard actions happen only inside the container display.

Use a macOS VM when the task needs native macOS apps. Docker provides a Linux desktop workspace, not a containerized macOS session.

Build

The Docker image installs the published ferrisgrid-cli package from crates.io. By default it installs the latest published version.

docker build -f docker/linux-workspace.Dockerfile -t ferrisgrid-linux-workspace .

Build a specific published version:

docker build \
  --build-arg FERRISGRID_VERSION=0.2.0 \
  -f docker/linux-workspace.Dockerfile \
  -t ferrisgrid-linux-workspace .

Run

docker run --rm -d \
  --name ferrisgrid-workspace \
  -p 6080:6080 \
  -v "$PWD:/workspace" \
  ferrisgrid-linux-workspace

Open the workspace viewer:

http://127.0.0.1:6080/vnc.html?autoconnect=1&resize=scale

Use from the host

docker exec ferrisgrid-workspace ferrisgrid doctor
docker exec ferrisgrid-workspace ferrisgrid observe

Write an action file in the repo, then execute it inside the container:

cat > .ferrisgrid/action.md <<'EOF'
status: action
action: click
screen_id: screen-1
x: 500
y: 500
button: left
wait_after_ms: 500
EOF

docker exec ferrisgrid-workspace ferrisgrid act --file .ferrisgrid/action.md

Backend

The image sets:

DISPLAY=:99
FERRISGRID_BACKEND=native-linux-x11
FERRISGRID_OUTPUT_DIR=/workspace/.ferrisgrid

The Linux backend uses X11 tools:

• xrandr or xdpyinfo for screen discovery
• ImageMagick import for screenshots
• xdotool for mouse and keyboard input

Resize

Set XVFB_SCREEN when starting the container:

docker run --rm -d \
  --name ferrisgrid-workspace \
  -p 6080:6080 \
  -e XVFB_SCREEN=1440x900x24 \
  -v "$PWD:/workspace" \
  ferrisgrid-linux-workspace