Connecting the Local API
Run browser profiles on your own machines with the VeilBrowser Local API.
The Local API runs on your machine (or fleet workers) and launches real browser instances from your profiles. Because browsers run locally, your browsing sessions never leave your infrastructure.
Install and run
Run the Local API as a Docker worker (recommended in a cluster) or with Bun in
development. By default it listens on http://localhost:3000.
Required environment:
| Variable | Purpose |
|---|---|
API_KEY | Shared secret for Local API requests (X-API-Key) |
SAAS_API_URL | Cloud control plane base URL (e.g. https://api.veilbrowser.net) |
VEIL_INSTALL_DIR | Root containing browsers/ and profiles/ trees |
For the full self-hosted path (cluster manager + workers), use the one-command install from Installation. Standalone development:
cd apps/local-api
cp .env.example .env # set API_KEY, SAAS_API_URL, VEIL_INSTALL_DIR
bun run devAuthenticate
Local API routes expect the worker's API_KEY in the X-API-Key header. The
organization key (VEIL_KEY) is used by the worker when calling the cloud
(license authorize, profile config, session tracking) — not as the Local API
request credential unless you configured them the same.
export WORKER_API_KEY="..." # matches the worker's API_KEYLaunch a profile
Ask the Local API to launch a profile and return a CDP endpoint:
curl -X POST http://localhost:3000/sessions/profile \
-H "X-API-Key: $WORKER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "profileId": "<profile-uuid>" }'The response contains a webSocketDebuggerUrl (a CDP URL) you can connect to
with Puppeteer, Playwright or any CDP client.
Keep keys secret
Treat API keys like passwords. Scope them per environment and rotate them regularly.
Next
Continue to Automation to drive the launched profile.