Skip to main content
Crawlstack provides a headless Docker container that bundles a stealth Chromium browser (Cloakbrowser), the Crawlstack extension, and optionally the Relay Server and a libSQL (SQLite) Server into a single deployable unit. This setup is ideal for running automated crawlers on a server or VPS while still managing them from your local browser extension in a unified “Cluster”.

​
Image

ghcr.io/crawlstack/cloakbrowser-node

​
Tags

TagExampleDescription
{version}-{YYYYMMDD}1.2.0-20250719Pinned extension version + build date. The date reflects browser freshness — stealth browsers older than ~3 releases may be detected.
{version}1.2.0Latest build of a specific extension version.
latestMost recent build overall.

​
Quick Start

docker run -d \
  --name crawlstack-node \
  -p 3002:3002 \
  -p 8080:8080 \
  -v crawlstack_data:/data \
  ghcr.io/crawlstack/cloakbrowser-node:latest
This starts a self-contained node with:
  • Internal relay server on port 3002
  • Internal libSQL database on port 8080
  • Persistent data at /data (browser profile + database)

​
Persistent Volumes

All persistent data lives under /data:
PathContents
/data/browser-dataChromium user profile, cookies, intercepted file downloads (OPFS)
/data/libsql-datalibSQL database files (crawlers, runs, extracted items)
/data/cloakbrowser-cacheCached Cloakbrowser stealth Chromium binary
You can mount them together or separately: 
# Single volume for everything
-v crawlstack_data:/data

# Separate volumes for browser and database
-v crawlstack_browser:/data/browser-data \
-v crawlstack_db:/data/libsql-data
Always mount persistent volumes. Without them, all data is lost when the container restarts.

​
Clustering with your Local Extension

To manage the headless node from your local browser:
  1. Open your local Crawlstack Dashboard → Settings.
  2. Under Database Connection, change the mode to External (LibSQL/Turso).
  3. Set the Database URL to http://localhost:8080 (or your server’s IP if remote).
  4. Under Global Configuration, set the API Relay URL to http://localhost:3002.
  5. Click Save Connection & Reload and Save Global Settings.
Your local extension and the remote Docker container now share the same database and relay. You can write a crawler script locally and trigger runs on the remote node.

​
External Services

The container automatically detects whether to start internal services based on environment variables:
ScenarioBehavior
CS_LIBSQL_URL not setStarts internal sqld on :8080
CS_LIBSQL_URL setConnects to external database, skips internal sqld
CS_RELAY_URL not setStarts internal relay on :3002
CS_RELAY_URL setConnects to external relay, skips internal relay

​
Example: External Database (Turso)

docker run -d \
  --name crawlstack-node \
  -p 3002:3002 \
  -v crawlstack_data:/data \
  -e CS_LIBSQL_URL=libsql://your-db.turso.io \
  -e CS_LIBSQL_TOKEN=your-auth-token \
  ghcr.io/crawlstack/cloakbrowser-node:latest

​
Example: External Relay (Cluster Worker)

docker run -d \
  --name crawlstack-worker \
  -v crawlstack_data:/data \
  -e CS_RELAY_URL=https://relay.example.com \
  -e CS_LIBSQL_URL=libsql://shared-db.turso.io \
  -e CS_LIBSQL_TOKEN=your-auth-token \
  ghcr.io/crawlstack/cloakbrowser-node:latest
No ports need to be exposed when using external services — the node connects outbound.

​
Environment Variables

VariableDescriptionDefault
CS_RELAY_URLExternal relay server URL. If not set, starts internal relay on :3002.Auto-detect
CS_LIBSQL_URLExternal libSQL database URL. If not set, starts internal sqld on :8080.Internal
CS_LIBSQL_TOKENAuth token for external libSQL database.None
CS_PROXYHTTP proxy for the browser (e.g., http://user:pass@proxy:8080).None
CS_NODE_TAGSComma-separated tags for this node. cloakbrowser and docker are always added.None
CS_DATA_DIRRoot data directory./data
CS_REMOTE_DEBUGGING_PORTChrome DevTools Protocol port.9222

​
Browser Freshness

The container uses a stealth-patched Chromium from Cloakbrowser. The browser binary is downloaded on first startup from official CloakHQ distribution channels and cached in the persistent volume at /data/cloakbrowser-cache. Subsequent restarts reuse the cached binary.
Use the date in the image tag (e.g., 1.2.0-20250719) to gauge browser freshness at a glance. Stealth browsers older than ~3 Chromium releases may trigger bot detection. Rebuild or pull a newer image regularly.
To force a browser update, delete the cached binary (/data/cloakbrowser-cache) and restart the container. Set CLOAKBROWSER_AUTO_UPDATE=false to prevent automatic update checks.