DEV Community

Cover image for Integrating BitBrowser with n8n: Automating Profile Creation via REST API
Digital Growth Pro
Digital Growth Pro

Posted on

Integrating BitBrowser with n8n: Automating Profile Creation via REST API

#ai #webdev #api #automation

If you manage dozens — or hundreds — of browser profiles for marketing operations, e-commerce, or QA testing, you already know the bottleneck: profile creation and configuration eat hours every week. Click here, set proxy there, copy-paste user agent, save, repeat. It's the kind of repetitive work that begs to be automated.

This guide walks through building a fully automated profile-creation pipeline using n8n (the open-source workflow automation tool) and the BitBrowser local REST API. By the end, you'll have a workflow that ingests a list of accounts from a Google Sheet, generates a unique fingerprint per profile, attaches a proxy from your provider, and creates the BitBrowser profile — all without a single click.

Why n8n + BitBrowser Is a Strong Pairing

n8n is self-hosted, node-based, and supports HTTP requests, scheduling, conditional logic, and 400+ native integrations. It runs locally or on a small VPS, which keeps your account data and credentials off third-party SaaS platforms — a real advantage for anyone handling sensitive marketing operations.

BitBrowser, on the other hand, exposes a complete local REST API on port 54345 by default. Every action you can perform manually in the GUI — creating a profile, editing fingerprints, launching a browser instance, deleting a profile — is available as a JSON endpoint. That makes it one of the most automation-friendly antidetect browsers on the market.

When you connect the two, n8n becomes your orchestration brain and BitBrowser becomes your execution engine. You can register for BitBrowser here if you don't already have an account — the free tier is enough to test this workflow with up to 10 profiles.

Prerequisites

Before building the workflow, make sure you have:

  • BitBrowser desktop client installed and running locally (the API only responds when the client is open)
  • n8n installed — either via Docker, npm (npm install n8n -g), or a hosted instance
  • A Google Sheet with columns for account name, proxy IP, proxy port, proxy username, and proxy password
  • A residential or ISP proxy provider (any provider that gives you authenticated host:port:user:pass credentials works)
  • Basic familiarity with HTTP requests and JSON

You'll also need to verify the BitBrowser API is reachable. Open a terminal and run:

curl http://127.0.0.1:54345/health
Enter fullscreen mode Exit fullscreen mode

If you get a 200 OK response, you're ready to proceed.

Step 1: Understanding the BitBrowser API Endpoints

BitBrowser's API is documented locally, but the three endpoints we'll use in this workflow are:

Endpoint Method Purpose
/browser/update POST Create or update a browser profile
/browser/open POST Launch a profile
/browser/close POST Close a running profile

The /browser/update endpoint is the workhorse. It accepts a JSON body containing the profile name, group ID, proxy configuration, fingerprint settings, and platform metadata. If you don't pass an id, it creates a new profile; if you pass an existing id, it updates that profile.

A minimal request body looks like this:

{
  "name": "Profile_001",
  "groupId": "0",
  "platform": "https://www.google.com",
  "proxyMethod": 2,
  "proxyType": "socks5",
  "host": "proxy.example.com",
  "port": "1080",
  "proxyUserName": "user123",
  "proxyPassword": "pass456",
  "browserFingerPrint": {
    "coreVersion": "124",
    "ostype": "PC",
    "os": "Win32",
    "version": "124",
    "userAgent": "",
    "language": "en-US",
    "timeZone": "America/New_York"
  }
}
Enter fullscreen mode Exit fullscreen mode

Leaving userAgent empty tells BitBrowser to auto-generate a consistent one based on the OS and browser version — which is almost always what you want for realistic fingerprints.

Step 2: Designing the n8n Workflow

The workflow has six nodes, each with a clear responsibility:

  1. Schedule Trigger — runs the workflow on a cron schedule (e.g., daily at 9 AM)
  2. Google Sheets — reads the queue of accounts to provision
  3. Set Node — formats the payload, generates randomized fingerprint values
  4. HTTP Request — calls the BitBrowser /browser/update endpoint
  5. IF Node — checks the response success flag
  6. Google Sheets (update) — writes the new profile ID back to the sheet, marking the row as "provisioned"

This pattern gives you idempotency: rows already marked as provisioned are skipped on the next run, so you can safely re-trigger the workflow without creating duplicates.

Step 3: Building the HTTP Request Node

This is the only node that needs careful attention. In n8n's HTTP Request node, configure:

  • Method: POST
  • URL: http://127.0.0.1:54345/browser/update
  • Authentication: None (the local API is unauthenticated by default — keep your firewall closed to external traffic)
  • Body Content Type: JSON
  • Specify Body: Using JSON

In the JSON body, reference the upstream Set node's output using n8n expressions:

{
  "name": "{{ $json.accountName }}",
  "groupId": "0",
  "platform": "https://www.google.com",
  "proxyMethod": 2,
  "proxyType": "{{ $json.proxyType }}",
  "host": "{{ $json.proxyHost }}",
  "port": "{{ $json.proxyPort }}",
  "proxyUserName": "{{ $json.proxyUser }}",
  "proxyPassword": "{{ $json.proxyPass }}",
  "browserFingerPrint": {
    "coreVersion": "124",
    "ostype": "PC",
    "os": "Win32",
    "version": "124",
    "language": "{{ $json.language }}",
    "timeZone": "{{ $json.timeZone }}"
  }
}
Enter fullscreen mode Exit fullscreen mode

When the workflow runs, n8n substitutes each {{ }} expression with the value from the corresponding row in your Google Sheet.

Step 4: Handling Mobile Profiles

If your operation involves managing mobile-only platforms like TikTok Shop seller dashboards or mobile-app onboarding, desktop profiles aren't enough. This is where the BitBrowser Cloud Phone service becomes useful — it provisions real Android cloud devices that you can control programmatically via the same API ecosystem.

You can integrate cloud phone provisioning into the same n8n workflow by adding a second branch that calls the BitCloudPhone service endpoints. The pattern is identical: read the row from the sheet, hit the appropriate endpoint, write back the device ID. This lets you mix desktop and mobile profile creation in a single automated pipeline — a powerful setup for teams that need consistent device-level isolation across both form factors.

Step 5: Error Handling and Retries

Production workflows always fail eventually. Proxies go offline, the BitBrowser client crashes, network blips happen. Build in resilience with these patterns:

Retry on failure: In the HTTP Request node settings, enable "Retry on Fail" with 3 attempts and a 2-second backoff. Most transient errors resolve on retry.

Error workflow: Set a global error workflow in n8n that posts to a Slack or Telegram channel whenever the main workflow fails. This way you find out about issues before your account list goes stale.

Health-check node: Add an initial HTTP Request node that hits /health on the BitBrowser API. If it returns anything other than 200, route the workflow to a notification branch and exit early. This prevents the workflow from silently failing when the BitBrowser client isn't running.

Step 6: Scaling Considerations

Once the basic workflow runs reliably, a few optimizations matter:

  • Batch size: Don't create 500 profiles in one workflow run. BitBrowser handles concurrent API calls fine, but file I/O on the underlying SQLite database can slow down. Process 20–50 profiles per run and schedule multiple runs throughout the day.
  • Rate limiting: Insert a Wait node (1–2 seconds) between profile creations if you're hitting any rate limits on your proxy provider's API.
  • Logging: Pipe the n8n execution logs to a persistent store (Postgres, Elasticsearch) so you can audit which profile was created when, with which proxy.
  • Version control: Export your n8n workflow as JSON and commit it to a Git repository. Workflows evolve; treat them like code.

Security Notes

The BitBrowser local API is unauthenticated by design — it assumes you're the only one with access to localhost. Two things to keep in mind:

  1. Never expose port 54345 to the public internet. If you need remote access, tunnel through SSH or use a service like Tailscale.
  2. If you run n8n on a separate machine, bind it to a private network or VPN. Don't put it behind a public reverse proxy without authentication enabled.

For most operators, running both n8n and BitBrowser on the same workstation (or the same internal VM) is the simplest and most secure setup.

Wrapping Up

The combination of n8n's orchestration capabilities and BitBrowser's open local API makes profile automation genuinely accessible — no custom code required, just JSON and HTTP nodes. Once you've built this workflow once, you'll wonder how you managed without it.

The same pattern extends to launching browsers on schedule, rotating proxies across existing profiles, archiving inactive accounts, and syncing profile metadata to a central dashboard. Treat the workflow you built today as the first brick in a much larger automation system.

If you're new to BitBrowser and want to test this workflow, you can create a free account here and have a working profile pipeline running in under an hour.

Happy automating.

Top comments (0)