Skip to content

Screenshots, video and browser scripts

Shoot, record and drive a web page inside a sandbox with a Chromium image, so nothing is exposed to the internet.

What this is

An agent or a CI job often needs to see a page it just built: a screenshot, a video of a flow, a GIF for a pull request, or a click through a form. You can do that inside a sandbox with a browser. The sandbox serves the page on localhost, a tool in the sandbox shoots it, and you read the file back. Nothing is forwarded to a preview link, so nothing is public.

The tool is a command called browse, built on Playwright. It needs Chromium, which Playwright's own image already has, so you start a sandbox on that image and install browse from a Sailfork release in one command. There is no registry to push to, and the release is rebuilt automatically whenever browse changes, so the line below always installs the newest. The source is in the Sailfork repository under deploy/browser.

Install it in a sandbox

Start a sandbox on the Playwright image, with the default 2 CPUs and 2 GB or more. That size was tested with 16 shots at once.

sailfork sandbox create --org acme --image mcr.microsoft.com/playwright:v1.65.1-noble --minutes 30
sailfork sandbox exec <id> -- "curl -fsSL https://sailfork.com/sailfork/cli/releases/download/browse-latest/setup.sh | sh"

The first command prints the sandbox id. Use it in the commands below. The second downloads browse (3 MB), checks its sha256, and starts Chromium once to prove the two match. For a caisson's code, pass the same --image to sailfork caisson test and run the setup line as part of your command.

The image is large (3.7 GB), but a host pulls it once and keeps it. If your organization or a host restricts images, allow it first, or the sandbox is refused and the message names the rule. --allowed-images replaces the whole list, so name the patterns you already allow as well, comma separated. A host's own list is set with sailfork sandbox host policy.

sailfork sandbox settings set --org acme --allowed-images "node:*,mcr.microsoft.com/playwright:*"

browse needs the Playwright image whose version it was built for. browse 1.0.0 goes with v1.65.1. If you start a different one, the setup stops with Chromium did not start and names the right image.

GIFs and ffmpeg

The Playwright image can record video but cannot make GIFs. The first time you ask for a GIF, browse installs ffmpeg with apt-get, which took about 11 seconds in testing and happens once per sandbox. A short run with a GIF took about a second after that. A sandbox that cannot reach an apt mirror or does not run as root cannot make GIFs, and says so.

Or build an image

If you start many sandboxes and want no setup at all, build an image that has everything and push it to a registry your hosts can pull from. The Dockerfile is in the same folder, and it adds ffmpeg so GIFs need no install.

git clone https://sailfork.com/sailfork/sailfork.git
docker build -t registry.example.com/acme/sailfork-browser:1 sailfork/deploy/browser
docker push registry.example.com/acme/sailfork-browser:1

That image is about 1.5 GB. Start sandboxes with it using --image, and skip the install line.

Take a screenshot

Serve a page inside the sandbox, then shoot it. The image includes python3, so a folder of files is one command away. Your own app works the same way: start it, then point browse at its port.

Start the server and shoot in the same command, so the server is still running when browse opens the page:

sailfork sandbox exec <id> -- "mkdir -p /srv/site /out && echo '<h1>hello</h1>' > /srv/site/index.html && (cd /srv/site && python3 -m http.server 8123 >/dev/null 2>&1 &) && sleep 1 && browse shot http://localhost:8123 /out/page.png --full"
sailfork sandbox cat <id> /out/page.png > page.png

sandbox cat writes the file's bytes unchanged, so redirect it to a file for a PNG, a WebM or a GIF.

A shot of a small page takes about a third of a second. --full captures the whole page instead of the first screen. To wait for something the page draws late, add --wait-for '#chart'.

Click through a page

For anything beyond a single shot, write a script and run it. A script is a JavaScript module whose default export is an async function. It gets { page, context, browser }, which are Playwright objects, so the Playwright documentation lists everything you can call.

flow.mjs

export default async ({ page }) => {
  await page.goto("http://localhost:8123");
  await page.fill("input", "fenil");
  await page.click("text=Go");
  await page.waitForSelector("#done");
};
sailfork sandbox put <id> flow.mjs /out/flow.mjs
sailfork sandbox exec <id> -- browse run /out/flow.mjs

Clicks and fills wait for the element to be ready, so a script does not need sleeps. The server from the screenshot example has to be running in the sandbox when the script runs, so start it in the same exec command as browse run, as above.

Record a video or a GIF

Add --video, --gif or both to browse run. It records the whole run.

sailfork sandbox exec <id> -- browse run /out/flow.mjs --video /out/flow.webm --gif /out/flow.gif --trace /out/flow.zip
sailfork sandbox cat <id> /out/flow.gif > flow.gif
  • The video is a 1280 by 800 WebM. A 30 second recording is about 0.4 MB.
  • The GIF is made from the video at 12 frames a second and 1280 pixels wide, about 1 MB for 30 seconds. Convert an existing video at a smaller size with browse gif /out/flow.webm /out/small.gif --fps 8 --width 640.
  • The trace is a Playwright trace with screenshots. Open it on your own machine with npx playwright show-trace flow.zip.

A run that fails still writes the video, the GIF and the trace, so you can see where it stopped. The command then exits 1 with a one-line error. If the run is stopped with SIGTERM, the video is saved before it exits.

Commands and options

CommandWhat it does
browse shot <url> <out.png>Open a page and save a screenshot
browse run <script.mjs>Run a script against a fresh page
browse gif <in.webm> <out.gif>Turn a recorded video into a GIF
OptionApplies toDefaultMeaning
--fullshotoffCapture the whole page. A page taller than 16384 pixels is clipped to that, and a notice says so.
--wait-for <selector>shotnoneWait for this element before the shot
--width, --heightshot, run1280, 800Viewport size in pixels. gif uses --width as the GIF width.
--timeout <seconds>shot, run15How long any navigation, wait or click may take
--video <file>runnoneSave the run as a WebM
--gif <file>runnoneSave the run as a GIF
--trace <file>runnoneSave a Playwright trace
--fps <n>gif, run12GIF frames per second

Many at once

Each shot starts its own Chromium, which holds hundreds of MB. browse lets only as many run at once as the sandbox has room for, counted from its memory (one per 768 MB) and its CPUs, and the rest wait their turn. Eight shots started together in a 2 GB sandbox all finished, and so did sixteen. Without the limit, five of eight were killed for running out of memory.

A call waits up to four times its --timeout for a turn, then fails with no browser slot free. If you run many at once, give the sandbox more memory with --memory.

What it cannot do

  • Only Chromium. There is no Firefox or WebKit.
  • No GPU, and none was tested. A page that depends on hardware graphics may not render.
  • A page on another site needs the sandbox's outbound network.

When something goes wrong

What you seeWhyWhat to do
Chromium did not start when installingThe sandbox's Playwright image is not the version this browse was built forStart the sandbox on the image the message names
GIFs need ffmpeg and apt-get could not install itThe sandbox cannot reach an apt mirror, or does not run as rootAllow outbound network, or use the built image, which has ffmpeg
page.goto: Timeout 15000ms exceededThe page did not finish loading in time, often because the server is not listening yetStart the server first, or pass a larger --timeout
page.waitForSelector: Timeout ...The element never appearedCheck the selector, or open the trace of a run
net::ERR_CONNECTION_REFUSEDNothing listens on that port in the sandboxStart the server in the same sandbox, and use localhost
net::ERR_UNSAFE_PORTChromium blocks a few well-known ports, such as 1Serve on another port
page is ... px tall, clipped to 16384pxA very long page was shot with --fullShoot a section with a script, or accept the clip
no browser slot freeToo many browse calls at once for the sandbox's memoryStart fewer at once, or create the sandbox with more --memory
sandbox cat writes a PNG that will not openThe output went to the terminal instead of a fileRedirect it: sandbox cat <id> /out/page.png > page.png

Loading Sailfork