name

fly-browser

description

Install and drive a long-lived, headed Chromium on a Fly.io machine the user already provisioned, exposed over CDP for AI automation with a live watch-along UI for humans. Use when the user wants to turn their existing Fly Machine into a remote browser, needs a persistent browser an agent can control across sessions, asks to scrape a page, automate a browser flow, fill a form, log into a site, take a screenshot, or otherwise drive a real remote browser. Also use when asked to install, reinstall, or check the status of the fly-browser stack on a box.

fly-browser

Turns a Fly Machine the user already owns and has provisioned into a persistent remote browser: a docker-compose stack (headed Chromium + CDP + KasmVNC watch-along UI) installed onto the box over SSH, kept running by systemd. This skill never creates, deploys, or destroys the Fly app/machine itself — that's the user's box, on their terms. It only installs software on it and drives the resulting browser.

Endpoint	Who uses it	Reachable from
CDP, port 9222	agents, via a WireGuard tunnel	nowhere publicly — only through `fly proxy` / `scripts/cdp-tunnel.sh`
KasmVNC web UI, port 3000	the human, to watch / take over	nowhere publicly — only through `fly proxy` / `scripts/watch-tunnel.sh`, behind HTTP Basic auth

The Chrome user-data dir persists at /var/lib/fly-browser/chrome-profile on the box's own disk, so logins, cookies, and extensions survive container and box restarts. It's a single shared browser — no per-session isolation unless you create separate browser contexts (see "Caveats" below).

Prerequisites

A Fly Machine the user has already created, reachable via fly ssh console -a <app-name> (true by default for Fly Machines whose image runs an OpenSSH server trusting Fly's CA — standard for most Fly base images / fly launch flows) with root access.
A systemd-based Linux distro on that box (Ubuntu/Debian, etc.).
The fly CLI installed locally and logged in (fly auth login).

If fly ssh console -a <app-name> doesn't connect, that's a box provisioning issue outside this skill's scope — sort that out with the user first.

Installing

scripts/remote-install.sh <app-name>

This uploads docker-compose.yml, the systemd unit, and install.sh to the box (fly ssh sftp put), then runs install.sh as root over fly ssh console -C. It's idempotent — installs Docker if missing, writes the compose stack and env file, installs + enables the systemd unit, and restarts the stack. Re-run it any time you change docker-compose.yml or systemd/fly-browser-chrome.service to push the update.

The first run generates and prints a watch-along username/password — save it, it isn't shown again. Re-run with WATCH_PASSWORD=... scripts/remote-install.sh <app-name> to rotate it (also restarts the stack, picking up the new credential).

Driving it for automation

CDP is never exposed publicly — you always go through a private WireGuard tunnel authenticated by your own fly auth login:

scripts/cdp-tunnel.sh <app-name>          # foreground; leave running
# -> tunnels 127.0.0.1:9222 to the box's CDP bridge

Run that in one terminal/background process for the duration of your automation session, then drive the browser through the local port.

agent-browser (if available — a CLI built for AI agents that returns accessibility snapshots with stable refs instead of selectors):

agent-browser --cdp 9222 open https://example.com
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 click @e2
agent-browser --cdp 9222 screenshot /tmp/page.png

Playwright (Python):

from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
    ctx = browser.contexts[0]
    page = ctx.new_page()
    page.goto("https://example.com")

Puppeteer (Node):

import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({ browserURL: "http://127.0.0.1:9222" });
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.disconnect();   // NEVER browser.close() — that kills the shared instance

Get the raw WebSocket debugger URL with curl -s http://127.0.0.1:9222/json/version | jq -r .webSocketDebuggerUrl.

When a human needs to step in

scripts/watch-tunnel.sh <app-name>        # foreground; leave running

Open http://127.0.0.1:3000, log in with the Basic Auth credentials from install, do the login / captcha / MFA, then say "continue" — your existing CDP connection keeps using the page they finished setting up.

Caveats

One shared browser. Every automation session and every human watcher attaches to the same Chromium instance and profile. Open your own tab or browser context rather than reusing/closing others' tabs.
Shared profile. A login one session performs is visible to the next. For isolation, create a new browser context (Playwright new_context()) rather than using the default one.
Never close the browser. Puppeteer: disconnect(), not close(). agent-browser: never close --all.
CDP is private by design. Don't publish port 9222/9223 as a public Fly service — unauthenticated CDP access is full remote control of the browser (cookies, sessions, arbitrary JS execution).
This skill doesn't manage the box's lifecycle. No app creation, no volumes, no fly deploy, no teardown. If the user wants the browser stack removed without destroying the box: fly ssh console -a <app-name> -C "systemctl disable --now fly-browser-chrome".

Troubleshooting

fly ssh console -a <app-name> hangs or refuses → the box itself isn't reachable over Fly SSH; not something this skill can fix. Check with the user how the box was provisioned.
fly proxy connects but CDP calls hang/reset → Chromium is still starting; retry in a few seconds, or check fly ssh console -a <app-name> -C "docker compose -f /opt/fly-browser/docker-compose.yml logs chrome".
Watch-along UI loads but shows a black screen → Chromium crashed inside its container. fly ssh console -a <app-name> -C "systemctl restart fly-browser-chrome" (the profile volume survives). If it keeps crashing, the box likely needs more memory — Chromium needs enough /dev/shm (the compose file sets shm_size: 1gb; that in turn needs enough host RAM).
401 on the watch-along tunnel → wrong Basic Auth credentials; re-run scripts/remote-install.sh <app-name> with WATCH_PASSWORD=... set to rotate them.
scripts/remote-install.sh fails uploading files → fly ssh sftp put needs the box reachable the same way fly ssh console does; if console works but sftp doesn't, retry (sftp session setup is occasionally flaky on first connect).
scripts/cdp-tunnel.sh / watch-tunnel.sh hang with no error → fly proxy tunnels over WireGuard (UDP), which some restricted/sandboxed network environments block outbound (only allowing HTTPS through a proxy). If the box itself is healthy (verify via fly ssh console), this is a local network limitation, not a problem with the installed stack.

name

fly-browser

description

fly-browser

Endpoint	Who uses it	Reachable from
CDP, port 9222	agents, via a WireGuard tunnel	nowhere publicly — only through `fly proxy` / `scripts/cdp-tunnel.sh`
KasmVNC web UI, port 3000	the human, to watch / take over	nowhere publicly — only through `fly proxy` / `scripts/watch-tunnel.sh`, behind HTTP Basic auth

Prerequisites

A Fly Machine the user has already created, reachable via fly ssh console -a <app-name> (true by default for Fly Machines whose image runs an OpenSSH server trusting Fly's CA — standard for most Fly base images / fly launch flows) with root access.
A systemd-based Linux distro on that box (Ubuntu/Debian, etc.).
The fly CLI installed locally and logged in (fly auth login).

If fly ssh console -a <app-name> doesn't connect, that's a box provisioning issue outside this skill's scope — sort that out with the user first.

Installing

scripts/remote-install.sh <app-name>

Driving it for automation

CDP is never exposed publicly — you always go through a private WireGuard tunnel authenticated by your own fly auth login:

scripts/cdp-tunnel.sh <app-name>          # foreground; leave running
# -> tunnels 127.0.0.1:9222 to the box's CDP bridge

Run that in one terminal/background process for the duration of your automation session, then drive the browser through the local port.

agent-browser (if available — a CLI built for AI agents that returns accessibility snapshots with stable refs instead of selectors):

agent-browser --cdp 9222 open https://example.com
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 click @e2
agent-browser --cdp 9222 screenshot /tmp/page.png

Playwright (Python):

from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
    ctx = browser.contexts[0]
    page = ctx.new_page()
    page.goto("https://example.com")

Puppeteer (Node):

import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({ browserURL: "http://127.0.0.1:9222" });
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.disconnect();   // NEVER browser.close() — that kills the shared instance

Get the raw WebSocket debugger URL with curl -s http://127.0.0.1:9222/json/version | jq -r .webSocketDebuggerUrl.

When a human needs to step in

scripts/watch-tunnel.sh <app-name>        # foreground; leave running

Caveats

One shared browser. Every automation session and every human watcher attaches to the same Chromium instance and profile. Open your own tab or browser context rather than reusing/closing others' tabs.
Shared profile. A login one session performs is visible to the next. For isolation, create a new browser context (Playwright new_context()) rather than using the default one.
Never close the browser. Puppeteer: disconnect(), not close(). agent-browser: never close --all.
CDP is private by design. Don't publish port 9222/9223 as a public Fly service — unauthenticated CDP access is full remote control of the browser (cookies, sessions, arbitrary JS execution).
This skill doesn't manage the box's lifecycle. No app creation, no volumes, no fly deploy, no teardown. If the user wants the browser stack removed without destroying the box: fly ssh console -a <app-name> -C "systemctl disable --now fly-browser-chrome".

Troubleshooting

fly ssh console -a <app-name> hangs or refuses → the box itself isn't reachable over Fly SSH; not something this skill can fix. Check with the user how the box was provisioned.
fly proxy connects but CDP calls hang/reset → Chromium is still starting; retry in a few seconds, or check fly ssh console -a <app-name> -C "docker compose -f /opt/fly-browser/docker-compose.yml logs chrome".
Watch-along UI loads but shows a black screen → Chromium crashed inside its container. fly ssh console -a <app-name> -C "systemctl restart fly-browser-chrome" (the profile volume survives). If it keeps crashing, the box likely needs more memory — Chromium needs enough /dev/shm (the compose file sets shm_size: 1gb; that in turn needs enough host RAM).
401 on the watch-along tunnel → wrong Basic Auth credentials; re-run scripts/remote-install.sh <app-name> with WATCH_PASSWORD=... set to rotate them.
scripts/remote-install.sh fails uploading files → fly ssh sftp put needs the box reachable the same way fly ssh console does; if console works but sftp doesn't, retry (sftp session setup is occasionally flaky on first connect).
scripts/cdp-tunnel.sh / watch-tunnel.sh hang with no error → fly proxy tunnels over WireGuard (UDP), which some restricted/sandboxed network environments block outbound (only allowing HTTPS through a proxy). If the box itself is healthy (verify via fly ssh console), this is a local network limitation, not a problem with the installed stack.