# 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](https://sailfork.com/docs/sandboxes) 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](https://sailfork.com/docs/sandboxes#preview-links), 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.

```sh
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](https://sailfork.com/docs/sandboxes#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`.

```sh
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.

```sh
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:

```sh
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](https://playwright.dev/docs/api/class-page) lists everything you can call.

```js title="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");
};
```

```sh
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.

```sh
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

| Command | What 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 |

| Option | Applies to | Default | Meaning |
| --- | --- | --- | --- |
| `--full` | `shot` | off | Capture the whole page. A page taller than 16384 pixels is clipped to that, and a notice says so. |
| `--wait-for <selector>` | `shot` | none | Wait for this element before the shot |
| `--width`, `--height` | `shot`, `run` | 1280, 800 | Viewport size in pixels. `gif` uses `--width` as the GIF width. |
| `--timeout <seconds>` | `shot`, `run` | 15 | How long any navigation, wait or click may take |
| `--video <file>` | `run` | none | Save the run as a WebM |
| `--gif <file>` | `run` | none | Save the run as a GIF |
| `--trace <file>` | `run` | none | Save a Playwright trace |
| `--fps <n>` | `gif`, `run` | 12 | GIF 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](https://sailfork.com/docs/sandboxes#resources-and-network).

## When something goes wrong

| What you see | Why | What to do |
| --- | --- | --- |
| `Chromium did not start` when installing | The sandbox's Playwright image is not the version this `browse` was built for | Start the sandbox on the image the message names |
| `GIFs need ffmpeg and apt-get could not install it` | The sandbox cannot reach an apt mirror, or does not run as root | Allow outbound network, or use the built image, which has ffmpeg |
| `page.goto: Timeout 15000ms exceeded` | The page did not finish loading in time, often because the server is not listening yet | Start the server first, or pass a larger `--timeout` |
| `page.waitForSelector: Timeout ...` | The element never appeared | Check the selector, or open the trace of a `run` |
| `net::ERR_CONNECTION_REFUSED` | Nothing listens on that port in the sandbox | Start the server in the same sandbox, and use `localhost` |
| `net::ERR_UNSAFE_PORT` | Chromium blocks a few well-known ports, such as 1 | Serve on another port |
| `page is ... px tall, clipped to 16384px` | A very long page was shot with `--full` | Shoot a section with a script, or accept the clip |
| `no browser slot free` | Too many `browse` calls at once for the sandbox's memory | Start fewer at once, or create the sandbox with more `--memory` |
| `sandbox cat` writes a PNG that will not open | The output went to the terminal instead of a file | Redirect it: `sandbox cat <id> /out/page.png > page.png` |

---

Every docs page: https://sailfork.com/llms.txt
