How to Give Claude Code a Real Browser: Headful Chromium in Docker with Playwright MCP

Mozilla/5.0 (Windows NT 10.0; Win64; x64) ... T3Code(Alpha)/0.0.42 Chrome/152.0.7977.65 Electron/44.1.0

# Google's Docker Hub mirror. Plain debian:trixie-slim works too if Hub is reachable.
FROM mirror.gcr.io/library/debian:trixie-slim

ENV DEBIAN_FRONTEND=noninteractive \
    TZ=Europe/London \
    LANG=en_GB.UTF-8 \
    LC_ALL=en_GB.UTF-8

RUN apt-get update && apt-get install -y --no-install-recommends \
      chromium chromium-sandbox tigervnc-standalone-server tigervnc-tools openbox \
      socat tini ca-certificates locales tzdata curl \
      fonts-noto-core fonts-noto-cjk fonts-noto-color-emoji fonts-liberation2 \
    && sed -i 's/^# *en_GB.UTF-8/en_GB.UTF-8/' /etc/locale.gen && locale-gen \
    && ln -sf /usr/share/zoneinfo/Europe/London /etc/localtime \
    && rm -rf /var/lib/apt/lists/* \
    && mkdir -m 1777 -p /tmp/.X11-unix \
    && useradd -m -u 1000 browser

COPY entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh

USER browser
WORKDIR /home/browser
EXPOSE 5900 9223
ENTRYPOINT ["tini", "--", "/usr/local/bin/entrypoint.sh"]

#!/bin/bash
# Xvnc (X server + VNC in one) -> openbox -> Chromium with CDP.
# Chromium's CDP only listens on loopback, so socat republishes it on :9223.
set -u
GEOMETRY="${GEOMETRY:-1920x1080}"
PROFILE=/profile

mkdir -p ~/.vnc
vncpasswd -f < /run/secrets/vnc_password > ~/.vnc/passwd
chmod 600 ~/.vnc/passwd

rm -f /tmp/.X1-lock /tmp/.X11-unix/X1
Xvnc :1 -geometry "$GEOMETRY" -depth 24 -rfbport 5900 -localhost no \
     -SecurityTypes VncAuth -PasswordFile ~/.vnc/passwd -AlwaysShared \
     -desktop agent-browser &
export DISPLAY=:1
for _ in $(seq 50); do [ -e /tmp/.X11-unix/X1 ] && break; sleep 0.1; done

openbox &
socat TCP-LISTEN:9223,fork,reuseaddr TCP:127.0.0.1:9222 &

# No GPU in the container, so WebGL comes from SwiftShader. A browser with no
# WebGL at all stands out to fingerprinting scripts.
# chromium-sandbox (setuid) keeps the sandbox on without needing userns in Docker.
# Chromium restarts itself if it crashes or someone closes the window over VNC.
# Clearing the singleton lock stops a stale one from a killed container
# blocking startup.
while true; do
  rm -f "$PROFILE"/Singleton*
  # Mark the last exit clean so Chromium doesn't show the "restore pages" bubble.
  [ -f "$PROFILE/Default/Preferences" ] && \
    sed -i 's/"exit_type":"Crashed"/"exit_type":"Normal"/' "$PROFILE/Default/Preferences"
  chromium \
    --user-data-dir="$PROFILE" \
    --remote-debugging-port=9222 \
    --remote-debugging-address=127.0.0.1 \
    --no-first-run --no-default-browser-check \
    --disable-dev-shm-usage \
    --use-angle=swiftshader --enable-unsafe-swiftshader \
    --lang=en-GB \
    --start-maximized \
    --window-size="${GEOMETRY/x/,}" \
    about:blank
  sleep 2
done

# Persistent headful Chromium for Claude Code (Playwright MCP over CDP),
# with a VNC view for me.
services:
  browser:
    build: .
    image: agent-browser:local
    container_name: agent-browser
    restart: unless-stopped
    shm_size: 2g
    # Chromium's setuid sandbox needs this to create namespaces. The container
    # runs as uid 1000, so only the setuid chrome-sandbox helper can use it.
    cap_add:
      - SYS_ADMIN
    mem_limit: 4g
    environment:
      GEOMETRY: 1920x1080
    volumes:
      - ./profile:/profile
    secrets:
      - vnc_password
    ports:
      # VNC: the tailnet address only. Not on the LAN, not on 0.0.0.0.
      - "100.x.y.z:5900:5900"
      # CDP: forge loopback only. Anything that reaches this owns the browser.
      - "127.0.0.1:9222:9223"

secrets:
  vnc_password:
    file: ./vnc_password

cd ~/agent-browser
umask 077
python3 -c "import secrets,string;a=string.ascii_letters+string.digits;print(''.join(secrets.choice(a) for _ in range(8)))" > vnc_password
mkdir -p profile
docker compose up -d --build
curl -s http://127.0.0.1:9222/json/version   # should return Chrome/...

npm i -g @playwright/mcp@0.0.82
claude mcp add --scope user browser --   ~/.npm-global/bin/playwright-mcp   --cdp-endpoint http://127.0.0.1:9222   --output-dir ~/agent-browser/shots

# 1200x630 cover, keeping the top of the page
shotfmt raw.png static/images/my-post.jpg --preset cover --focus top

# crop a region, add rounded corners and a shadow, cap at 1600 wide
shotfmt raw.png static/images/my-post-dashboard.jpg --box 0,95,1080,805 --frame --preset inline

# pixelate a region you can't clean up in the page itself
shotfmt raw.png out.png --blur 40,300,260,24

() => {
  // Hide cookie banners, consent widgets, chat bubbles and "buy me a coffee"
  // buttons before a screenshot. Anything fixed or sticky goes, unless it's the
  // site's own header/nav. So does any shadow-DOM widget outside the page
  // content (Google's consent bubble lives in one). A MutationObserver catches
  // widgets that re-inject themselves. Returns how many elements were hidden.
  const keep = (e) => e.closest('header, nav, main, article');
  let hidden = 0;
  const hideEl = (e) => { if (e.style.display !== 'none') { e.style.setProperty('display', 'none', 'important'); hidden++; } };
  const sweep = (root) => {
    for (const e of root.querySelectorAll('*')) {
      const pos = getComputedStyle(e).position;
      if ((pos === 'fixed' || pos === 'sticky') && !keep(e)) hideEl(e);
      if (e.shadowRoot) {
        if (!keep(e)) hideEl(e);
        else sweep(e.shadowRoot);
      }
    }
  };
  sweep(document);
  // Batch re-sweeps to one per frame; busy pages like eBay mutate constantly.
  let queued = false;
  new MutationObserver(() => {
    if (queued) return;
    queued = true;
    requestAnimationFrame(() => { queued = false; sweep(document); });
  }).observe(document.documentElement, { childList: true, subtree: true });
  return hidden;
}

#!/usr/bin/env python3
"""Crop, blur, frame, resize and compress a screenshot.

Made for agent browser screenshots going into chat or a Hugo blog.
Coordinates are pixels of the input image (CSS px for scale=css shots).

  shotfmt in.png out.jpg --preset cover --focus top
  shotfmt in.png out.jpg --box 0,120,1280,600 --max-width 1600
  shotfmt in.png out.png --blur 40,300,260,24 --frame
"""
import argparse
import os
import sys

from PIL import Image, ImageDraw, ImageFilter, ImageOps

PRESETS = {
    # PaperMod cover / og:image: exactly 1200x630.
    "cover": dict(size=(1200, 630), max_width=None),
    # Inline post images: the blog's recent posts are 1600 wide or less.
    "inline": dict(size=None, max_width=1600),
    # Something small enough to glance at in chat.
    "chat": dict(size=None, max_width=1280),
}


def box(s):
    try:
        x, y, w, h = (int(float(v)) for v in s.split(","))
    except ValueError:
        raise argparse.ArgumentTypeError(f"expected x,y,w,h, got {s!r}")
    return x, y, w, h


def size(s):
    try:
        w, h = (int(v) for v in s.lower().split("x"))
    except ValueError:
        raise argparse.ArgumentTypeError(f"expected WxH, got {s!r}")
    return w, h


def fit(img, target, focus):
    """Crop to the target aspect ratio around a focus point, then resize."""
    tw, th = target
    w, h = img.size
    want = tw / th
    if w / h > want:  # too wide: trim the sides
        nw = round(h * want)
        x = {"left": 0, "right": w - nw}.get(focus, (w - nw) // 2)
        img = img.crop((x, 0, x + nw, h))
    else:  # too tall: trim top/bottom
        nh = round(w / want)
        y = {"top": 0, "bottom": h - nh}.get(focus, (h - nh) // 2)
        img = img.crop((0, y, w, y + nh))
    return img.resize(target, Image.LANCZOS)


def frame(img, pad, bg, radius):
    """Rounded corners, a hairline border and a soft shadow on a plain background."""
    w, h = img.size
    mask = Image.new("L", (w, h), 0)
    ImageDraw.Draw(mask).rounded_rectangle((0, 0, w - 1, h - 1), radius, fill=255)
    ImageDraw.Draw(img).rounded_rectangle((0, 0, w - 1, h - 1), radius, outline=(0, 0, 0, 40))

    canvas = Image.new("RGBA", (w + pad * 2, h + pad * 2), bg)
    shadow = Image.new("RGBA", canvas.size, (0, 0, 0, 0))
    ImageDraw.Draw(shadow).rounded_rectangle(
        (pad, pad + pad // 6, pad + w, pad + h + pad // 6), radius, fill=(0, 0, 0, 90))
    canvas = Image.alpha_composite(canvas, shadow.filter(ImageFilter.GaussianBlur(pad / 3)))
    canvas.paste(img, (pad, pad), mask)
    return canvas


def main():
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("input")
    p.add_argument("output", help="format from extension: .jpg .png .webp")
    p.add_argument("--preset", choices=PRESETS)
    p.add_argument("--box", type=box, help="crop x,y,w,h before anything else")
    p.add_argument("--blur", type=box, action="append", default=[],
                   help="pixelate x,y,w,h (repeatable), in input coordinates")
    p.add_argument("--size", type=size, help="exact WxH output, cropping to fit")
    p.add_argument("--focus", choices=["top", "center", "bottom", "left", "right"], default="center",
                   help="what to keep when cropping to --size/cover (default center)")
    p.add_argument("--max-width", type=int)
    p.add_argument("--frame", action="store_true", help="rounded corners + shadow on a padded background")
    p.add_argument("--pad", type=int, default=48)
    p.add_argument("--bg", default="#f2f2f2")
    p.add_argument("--quality", type=int, default=82)
    p.add_argument("--force", action="store_true", help="overwrite an existing output")
    a = p.parse_args()

    if os.path.exists(a.output) and not a.force:
        sys.exit(f"{a.output} exists; pass --force to overwrite")

    preset = PRESETS.get(a.preset, {})
    target = a.size or preset.get("size")
    max_width = a.max_width or preset.get("max_width")

    img = ImageOps.exif_transpose(Image.open(a.input)).convert("RGBA")
    src = img.size

    for x, y, w, h in a.blur:
        region = img.crop((x, y, x + w, y + h))
        small = region.resize((max(1, w // 12), max(1, h // 12)), Image.BILINEAR)
        img.paste(small.resize(region.size, Image.NEAREST), (x, y))

    if a.box:
        x, y, w, h = a.box
        img = img.crop((x, y, min(x + w, src[0]), min(y + h, src[1])))

    if a.frame:
        img = frame(img, a.pad, a.bg, radius=12)

    if target:
        img = fit(img, target, a.focus)
    elif max_width and img.width > max_width:
        img = img.resize((max_width, round(img.height * max_width / img.width)), Image.LANCZOS)

    ext = os.path.splitext(a.output)[1].lower()
    os.makedirs(os.path.dirname(os.path.abspath(a.output)), exist_ok=True)
    if ext in (".jpg", ".jpeg"):
        flat = Image.new("RGB", img.size, a.bg)
        flat.paste(img, mask=img.getchannel("A"))
        flat.save(a.output, "JPEG", quality=a.quality, optimize=True, progressive=True)
    elif ext == ".webp":
        img.save(a.output, "WEBP", quality=a.quality, method=6)
    elif ext == ".png":
        img.save(a.output, "PNG", optimize=True)
    else:
        sys.exit(f"unsupported output type {ext!r}")

    print(f"{a.output}  {src[0]}x{src[1]} -> {img.width}x{img.height}  "
          f"{os.path.getsize(a.output) // 1024} KB")


if __name__ == "__main__":
    main()

Read https://exitcode0.net/posts/claude-code-browser-docker-playwright-mcp/ and set up
the same agent browser on this machine. Check with me before you pick ports or bind addresses.