Docs · Start

Install & run

Scalebrowser runs on your own machine. On Windows that is a desktop app you install once; on Linux it is a single binary you run as a service. Both are the same daemon, and both talk the same API.

Windows — the desktop client

The Windows client is the shortest path: it installs the daemon alongside itself, supervises it, fetches the engine on first start and renders the management UI. Windows 10 or 11, 64-bit.

1. Sign in at cp.scalebrowser.net and open Download. The button carries the current version.
2. Run the installer. It installs for the current user under %LOCALAPPDATA%\Programs and asks for no administrator rights.
3. Start Scalebrowser. On first launch it downloads and verifies the engine; the app tells you while that is happening, and a profile cannot start before it has finished.
4. Create a profile in the UI, or point an agent at the API — see MCP, direct CDP or REST.

Where things end up

Uninstalling removes the application and leaves the data directory alone, so your profiles survive a reinstall. Closing the app stops the daemon, and the daemon stops the browsers it started — nothing is left running in the background.

Linux — the self-hosted daemon

On a Linux host the daemon is a single binary. Two supported shapes, same binary: a container (Docker Compose) or a systemd service. Both keep everything under one data directory.

Before you start

• A 64-bit Linux host with a real GPU exposed to the process.
• RAM to spare: each headless Chromium takes roughly 250–400 MB. The daemon refuses launches past its configured budget instead of running the host out of memory.
• The daemon build and the signed engine. Neither sits on a public registry — both are signed artefacts that come with your subscription. Write to [email protected] if you do not have them yet.

Run it

Two secrets first — an API token clients authenticate with, and the key that encrypts stored proxy credentials at rest:

$ openssl rand -hex 32   # SCALEBROWSER_BEARER_TOKEN
$ openssl rand -hex 32   # SCALEBROWSER_MASTER_KEY

Put both into the environment the daemon starts with. Then start it. With Docker Compose that is one command, and the logs show it binding and probing the host GPU:

$ docker compose up -d
$ docker compose logs -f daemon

Running the binary directly works the same way; a hardened systemd unit ships with the deployment files. The daemon writes <data_dir>/runtime.json once its listeners are up — that file is the readiness signal, and it is what the container healthcheck watches.

Install the engine

The engine is not baked into the image; it is installed into the data directory once, and verified on the way in and at every launch. Point the command at the archive you were given:

$ scalebrowser-daemon engine install ./engine-linux-x64-<version>.tar.zst
$ scalebrowser-daemon engine list

engine list shows the installed builds and which one is pinned. Four more subcommands round it out: verify re-checks an installed build, pin makes a version the active one, rollback returns to the previously pinned build, and update applies a signed delta package instead of a full download.

Verification is not a formality. Installing and launching both check the archive's SHA-256, its signature against the release keys compiled into the daemon, and a signed manifest listing every file in the package. A file the manifest does not name is refused outright, so a tampered build cannot launch, and it cannot be installed in the first place.

Check that it works

/health is public — it answers without a token, which makes it the right thing for a monitor to poll. Everything under /v1 needs the bearer token:

$ curl http://127.0.0.1:8787/health
$ curl http://127.0.0.1:8787/v1/profiles \
    -H "Authorization: Bearer $SCALEBROWSER_BEARER_TOKEN"

Over TLS the scheme is https, and a self-signed test certificate needs curl -k. If the first call answers and the second returns your (empty) profile list, the daemon is up and your token is right.

Ports

The AdsPower adapter is unauthenticated by design, so it may only ever bind to a loopback address — the daemon refuses to start if it is pointed anywhere else. The same applies to the Prometheus endpoint, which is unauthenticated plaintext and warns loudly if you bind it publicly.

Configuration

Four layers, later ones win:

1. built-in defaults
2. a TOML config file (--config)
3. environment variables
4. command-line flags

The settings most installs touch:

The data directory defaults to %ProgramData%\Scalebrowser on Windows and to ./data next to the binary elsewhere; the Windows client overrides it with its own per-user location. Everything the daemon owns lives there — the SQLite database, installed engines, each profile's browser directory, the at-rest key and runtime.json. Back that one directory up and you have backed up your profiles.

The API token

If you do not supply a token, the daemon can mint one and store it in the data directory:

$ scalebrowser-daemon --generate-token

On a loopback bind the daemon prints the management UI's address on start, with the token in the URL fragment so the page signs itself in. That happens only on loopback: on a network address the URL stays token-free and the token is printed separately, because a URL carrying a credential must not be handed around.

Next

• MCP server — connect an AI agent and let it operate a page.
• Direct CDP — drive the browser yourself, from Python or Node.
• REST API — create, start and manage profiles.
• Coherence & proxies — what is checked before a profile is allowed to start.