Launch BrowserBox on a GitHub Actions runner and get back a usable login link.

This action is a thin wrapper around the existing BrowserBox CLI flows. It installs BrowserBox from browserbox.io, applies your license key, starts the service, and returns the resulting URL as an action output.

BrowserBox requires a valid license key. You can get one at browserbox.io.

On runners, the action defaults to a minimal runtime footprint:

• BBX_MINIMAL_MODE=true
• BBX_NO_UPDATE=true

That means the action starts only bb-main unless you explicitly opt into the full multi-service cluster.

browserbox-action v1 is intentionally narrow:

• Linux runners only
• tunnel: none
• tunnel: cloudflare
• tunnel: tor
• ZeroTier is intentionally excluded from v1

The repo is kept minimal so it can stay compatible with GitHub Action publishing requirements for a dedicated public action repository.

name: BrowserBox demo

on:
  workflow_dispatch:

jobs:
  browserbox:
    runs-on: ubuntu-latest
    steps:
      - name: Launch BrowserBox
        id: browserbox
        uses: BrowserBox/browserbox-action@v1
        with:
          license-key: ${{ secrets.BROWSERBOX_LICENSE_KEY }}
          tunnel: cloudflare
          port: 8080
          service-mode: minimal

      - name: Print BrowserBox URL
        run: |
          echo "Login link: ${{ steps.browserbox.outputs.login-link }}"
          echo "Base URL:   ${{ steps.browserbox.outputs.base-url }}"

By default, the launch step exports:

BBX_MINIMAL_MODE=true
BBX_NO_UPDATE=true

This keeps the runner footprint small and avoids update checks during action-driven launches.

If you need the full BrowserBox cluster because you are mapping or using the auxiliary services yourself, set:

with:
  service-mode: full

Runs:

bbx stop
bbx setup -p <port> --hostname <hostname>
bbx start

This is the local runner mode. It is useful when later steps in the same job will talk to BrowserBox directly.

Runs:

bbx cf-run --background --port <port>

This is the easiest public demo path for v1.

Runs:

bbx setup --port <port> --hostname <hostname>
bbx tor-run --no-darkweb

For v1 this action uses the onion-service path only. It does not enable the "browse outward over Tor" mode.

This action is written for GitHub-hosted Ubuntu runners in v1.

If the runner is missing prerequisites, the install step uses apt-get to install:

• curl
• jq
• sudo
• vim-common for xxd

• Main BrowserBox project: github.com/BrowserBox/BrowserBox
• BrowserBox website and licensing: browserbox.io
• Additional examples: docs/usage.md

• GitHub runners are ephemeral. Your BrowserBox session only lives as long as the job and runner do.
• This action does not yet implement ZeroTier.
• This action does not currently provide a cleanup/post step. Runner teardown is relied on for v1.

This repository does not grant any license to BrowserBox itself. BrowserBox usage requires a valid license key from browserbox.io.