xBrowserSync API

Fork of the xBrowserSync REST API with MySQL, PostgreSQL, and SQLite3 support, current dependencies, and a hardened Docker image. Application behaviour stays a drop-in replacement of the original. There is no mass migration: each user must migrate their own bookmarks.

Credits

Based on:

• xbrowsersync/api — original API
• swarnat/xbrowsersync-api — TypeORM / SQL backends and Node 22 refresh

This repository continues that lineage with Node 24 LTS, patched dependencies, and scheduled image rebuilds.

Supported tags

Images are published to ghcr.io/rwjack/xbrowsersync-api.

Tag	Meaning
1.3.0	Current API version; rebuilt on the 1st and 15th with fresh OS/Node packages
1.3.0-2026.8.1	Pin to a specific release or scheduled rebuild (YYYY.M.D UTC)
latest	Alias of the current version tag after each release/rebuild

Version naming follows the API itself. Multi-arch: amd64, arm64.

Dockerfile: Dockerfile (currently API 1.3.0, Node 24 LTS on Debian Trixie).

Quick reference

• Issues: https://github.com/rwjack/xbrowsersync-api/issues
• PRs: https://github.com/rwjack/xbrowsersync-api/pulls
• Source: https://github.com/rwjack/xbrowsersync-api

What is xBrowserSync?

xBrowserSync is a free tool for syncing browser data between different browsers and devices, built for privacy and anonymity. For full details, see www.xbrowsersync.org.

This repository is the REST API that client applications talk to. API methods are documented on the home page of each running service (same as api.xbrowsersync.org for the official instance).

How to use this image

docker run --rm -p 8080:8080 ghcr.io/rwjack/xbrowsersync-api:1.3.0

Or examples/docker-compose.yaml:

docker compose -f examples/docker-compose.yaml up

Open http://localhost:8080. Configure via examples/xbrowsersync.env or a bind-mounted settings.json.

Persistent data

SQLite (the default) writes /usr/src/app/data/xbrowsersync.sqlite3. Mount a volume there:

volumes:
  - data:/usr/src/app/data

Image variants

ghcr.io/rwjack/xbrowsersync-api:1.3.0

Recommended pin. Same API version across rebuilds; OS and Node packages stay current via the bi-monthly rebuild workflow. Each release and scheduled rebuild also publishes a dated tag like 1.3.0-2026.8.1.

The runtime image is Node 24 LTS on Debian Trixie. npm/corepack/yarn are stripped after the build; they are not needed at runtime.

ghcr.io/rwjack/xbrowsersync-api:latest

Floating alias of the current release, updated on releases and scheduled rebuilds.

Manual installation

Docker is the recommended way to run the service. To run it on the host instead:

Prerequisites

• Node.js 24 or newer
• A database: SQLite (default, no extra server), or MySQL / PostgreSQL

1. Clone

git clone https://github.com/rwjack/xbrowsersync-api.git
cd xbrowsersync-api

2. Install and build

npm install
npm run build

Use npm install --unsafe-perm if you hit permissions errors while compiling sqlite3.

3. Database

SQLite

The database file is data/xbrowsersync.sqlite3 relative to the compiled app (in Docker: /usr/src/app/data/xbrowsersync.sqlite3). Mount a volume on that path for persistence. Override the path with XBSAPI_DB_FILEPATH.

MySQL or PostgreSQL

Create a database and user, then set:

• XBSAPI_DB_TYPE — mysql or postgres
• XBSAPI_DB_HOST
• XBSAPI_DB_NAME
• XBSAPI_DB_USERNAME
• XBSAPI_DB_PASSWORD
• XBSAPI_DB_PORT — default 3306 (use 5432 for PostgreSQL)

4. Configuration

Defaults live in src/config.default.ts (compiled into the image). Override with environment variables from examples/xbrowsersync.env, or with config/settings.json for values that should persist outside env.

Copy only the keys you change into settings.json so later default updates still apply. Example:

{
  "status": {
    "message": "Welcome to my xBrowserSync service!"
  }
}

Restart the service after changing config.

Setting	Description	Default	Environment variable
allowedOrigins	Origins allowed to call the service (String or RegExp). Empty = all origins	[]	XBSAPI_ALLOWEDORIGINS (comma-separated)
dailyNewSyncsLimit	Max new syncs per user per day. 0 disables the limit	3	XBSAPI_DAILYNEWSYNCSLIMIT
db.type	sqlite, mysql, or postgres	sqlite	XBSAPI_DB_TYPE
db.host	Database hostname (MySQL/PostgreSQL)	127.0.0.1	XBSAPI_DB_HOST
db.name	Database name (MySQL/PostgreSQL)	xbrowsersync	XBSAPI_DB_NAME
db.username	Database user	(empty)	XBSAPI_DB_USERNAME
db.password	Database password	(empty)	XBSAPI_DB_PASSWORD
db.port	Database port	3306	XBSAPI_DB_PORT
db.filepath	SQLite file path	data/xbrowsersync.sqlite3	XBSAPI_DB_FILEPATH
location	ISO 3166-1 alpha-2 location code shown to clients	DE	XBSAPI_LOCATION
log.file.enabled	File logging (on when log.file.path / XBSAPI_LOG_FILE_PATH is set)	off	XBSAPI_LOG_FILE_PATH
log.file.level	trace, debug, info, warn, error, fatal	debug	XBSAPI_LOG_FILE_LEVEL
log.file.path	Log file path	/var/log/xBrowserSync/api.log	XBSAPI_LOG_FILE_PATH
log.file.rotatedFilesToKeep	Rotated files to keep	5	XBSAPI_LOG_FILE_KEEPROTATION
log.file.rotationPeriod	Bunyan rotation period (1d, 1h, …)	1d	XBSAPI_LOG_FILE_ROTATIONPERIOD
log.stdout.enabled	Log to stdout	true
log.stdout.level	Stdout log level	info	XBSAPI_LOG_STDOUT_LEVEL
maxSyncs	Max stored syncs. 0 disables	5242	XBSAPI_MAXSYNCS
maxSyncSize	Max sync payload in bytes (compressed + encrypted client-side)	512000	XBSAPI_MAXSYNCSIZE
server.behindProxy	Trust X-Forwarded-For. Only enable behind a real proxy	false	XBSAPI_SERVER_BEHINDPROXY
server.trustedProxies	Number of trusted reverse proxies when behindProxy is set	0	XBSAPI_SERVER_TRUSTED_PROXIES
server.host	Listen address	0.0.0.0
server.https.enabled	Serve over HTTPS	false
server.https.certPath	TLS certificate path	(empty)
server.https.keyPath	TLS private key path	(empty)
server.port	Listen port	8080
server.relativePath	Path prefix; must start and end with /	/	XBSAPI_SERVER_RELATIVEPATH
status.allowNewSyncs	Allow creating new syncs (existing IDs still work if false)	true	XBSAPI_STATUS_ALLOWNEWSYNCS
status.message	Message shown in the client status panel (markdown, ≤130 chars)	(empty)	XBSAPI_STATUS_MESSAGE
status.online	If false, clients cannot connect	true	XBSAPI_STATUS_ONLINE
throttle.maxRequests	Max requests per throttle.timeWindow. 0 disables	1000	XBSAPI_THROTTLE_MAXREQUESTS
throttle.timeWindow	Throttle window in milliseconds	300000	XBSAPI_THROTTLE_TIMEWINDOW

5. Logs

If file logging is enabled, create the directory for log.file.path and make sure the process user can write there.

6. Run

node dist/api.js

Building

npm run build

Testing

Unit, integration, and e2e tests are included.

npm run test

e2e tests expect a SQL test database (see tests.db / tests.port in config), not MongoDB.

DB migrations

TypeORM migrations live under src/migrations. Generate a new one with:

npm run typeorm:migration:generate -- ./src/migrations/<migrationname>

Then add the class to the migrations array in src/db.ts.

Other implementations

• sbogomolov/xbrowsersync-gcf — Google Cloud Functions + Firestore
• txchen/xbrowsersync-cfw — Cloudflare Worker + KV

VS Code

Launch configurations:

1. Debug API — compile and debug the API
2. Debug docs — API home page in Chrome
3. Run unit/integration tests — *.spec.ts under src
4. Run e2e tests — test/e2e

VSCodium is a telemetry-free VS Code build if you prefer that.

Issues

Use rwjack/xbrowsersync-api issues for this fork (image, rebuilds, and API changes here). Upstream API issues still belong in xbrowsersync/api.