Jet Browser

Jet Browser

Overview

Use Jet Browser as a replaceable browser-runtime boundary for an agent or deterministic test runner. It runs one isolated WPE WebKit session per container and exposes ordered JSONL commands for navigation, native input, semantic inspection, screenshots, and cleanup.

Keep model selection, reasoning, credentials, and orchestration in the calling project. Jet Browser is a browser runtime, not an agent framework, hosted proxy network, anti-bot service, or bridge to a user's personal Chrome profile.

When to Use This Skill

• Use when a project needs a self-hosted browser process with an explicit container lifecycle.
• Use when a harness needs framework-neutral, ordered JSONL instead of a bundled agent loop.
• Use when native pointer, keyboard, touch, DOM, and screenshot evidence should share one runtime.
• Use when a repository needs a reproducible offline smoke test or GitHub Actions browser-runtime check.
• Do not use this skill to control an already-running personal Chrome or reuse its logged-in state; use the environment's permission-approved CDP workflow for that.

Safe Setup and Verification

1. Establish the boundary before downloading

Confirm that the user wants a separate Jet Browser container rather than their daily browser. Check for Docker and Node.js 24+, and report a missing requirement instead of claiming the runtime was verified.

For a new checkout or upgrade, identify an immutable release or full commit, inspect the repository's package.json, lifecycle scripts, lockfile, Dockerfiles, executable files, symlinks, network access, and credential handling, and summarize what will run. Obtain explicit approval before downloading and again before installing dependencies, building images, or starting containers. A Git commit pin provides reproducibility, not proof of trust.

The v0.6.7 source commit reviewed for this catalog entry is:

882b17ab1b865560f17dbfeeeea0a7b40b95a146

Review a newer source tree independently before changing that pin.

2. Run the standalone acceptance flow

After the approvals above, install the pinned source's exact lockfile dependencies and run its standalone check:

npm ci
npm run standalone

Treat the command's observed JSON result as the acceptance check. A passing run must start the local page, verify the JavaScript marker, type through the native input path, capture a PNG, keep the smoke browser's outbound network disabled, and shut the container down cleanly.

For source changes, also run:

npm test
cargo test --all-targets

Never report a pass when Docker, Node.js, the image build, browser startup, native input, DOM verification, screenshot capture, or cleanup did not actually complete.

3. Integrate the documented contract

Read docs/demo.md for the container lifecycle and docs/agent-tools.md for model-facing declarations. Prefer the versioned declarations exported by sdk/tools.mjs; do not invent tool names, input fields, or response shapes.

Send one JSON command per line and consume one JSON response per line. Preserve ordering, bound inputs and outputs in the calling harness, and close the session in guaranteed cleanup. Keep one container per mutually untrusted session, mount profile or download paths explicitly, and never pass unrelated host credentials into the container.

Use semantic evidence for target selection and screenshots for visual verification when both are available. Treat evaluation, imported profiles, downloads, and outbound network access as privileged capabilities that require the calling application to define its own authorization and policy gates.

Examples

Example 1: Verify a pinned source checkout

After inspecting the pinned source and receiving the required approvals:

git clone --filter=blob:none --no-checkout https://github.com/masakaai/jet-browser.git
git -C jet-browser checkout --detach 882b17ab1b865560f17dbfeeeea0a7b40b95a146
cd jet-browser
npm ci
npm run standalone

Report the exact command result and which acceptance assertions ran. Do not translate a partial build or startup log into a successful verification.

Example 2: Verify Jet Browser in GitHub Actions

Pin the Action to the reviewed full commit rather than a moving branch or tag:

permissions:
  contents: read

jobs:
  verify-browser-runtime:
    runs-on: ubuntu-latest
    steps:
      - name: Verify Jet Browser
        uses: masakaai/jet-browser@882b17ab1b865560f17dbfeeeea0a7b40b95a146 # v0.6.7

This checks the public linux/amd64 release image on a GitHub-hosted Linux runner. Review the Action source and repository workflow permissions before use.