Tabrelay

Drive your real, logged-in Chrome from the command line or an AI agent.

Tabrelay is a small Python command plus a Chrome extension. Open pages, run JavaScript, click, type, upload files and take screenshots in the browser you already use, with your profile, cookies, logins and 2FA, while you keep working in the foreground.

Download the latest release Source on GitHub

Why Tabrelay

Your real browser

No separate automation browser to log in to, no copied cookies, no test profile. Jobs run in the Chrome you use every day.

No focus stealing

Jobs run in background windows and tabs, and pages are told they have focus, so uploads and lazy pages keep working while you type elsewhere.

Several profiles

Load the extension in each Chrome profile; every job goes to exactly the profile you name.

CLI first

Every action is a shell command that prints plain text or JSON, so any script, cron job or AI agent that can run a command can use it.

How it works

The command queues a job on a small server bound to localhost. The extension picks it up and carries it out with the Chrome DevTools Protocol, then sends the result back. Python 3.10+ standard library only, no build step, no npm.

$ tabrelay ping
{"ok": true, "version": "0.1.0", "profile": "you@example.com", "sites": 1}
$ TAB=$(tabrelay open https://example.com/)   # new background window
$ tabrelay eval "$TAB" 'document.title'
"Example Domain"
$ tabrelay click "$TAB" 'document.querySelector("a")'
$ tabrelay shot "$TAB" example.png
$ tabrelay close "$TAB"

It is also a Python module: evaluate, wait_for, click, fill_lines, set_files, shot and raw cdp calls for your own scripts.

Security model

A local token

A random secret, created on first use with mode 600. The server only accepts jobs that carry it, and the extension only runs jobs that carry it.

Localhost only

The server binds to 127.0.0.1 and refuses foreign Host headers and web page origins, so websites you visit can't drive it.

Allow-list in the extension

The extension acts only on sites you listed in its own options page. Nothing the command line sends can widen that list.

No telemetry: the extension talks to 127.0.0.1 and the pages it drives, nothing else. It is a guard rail, not a sandbox; read the security notes before you let an agent loose.

Install

  1. Download tabrelay-VERSION.tar.gz from the latest release and unpack it.
  2. Run ./bin/tabrelay config once to create the local token.
  3. In Chrome open chrome://extensions, turn on Developer mode, click Load unpacked and pick the extension/ folder.
  4. Add the sites you want to automate on the extension's options page, then run ./bin/tabrelay ping.

Needs Chrome (or another Chromium browser with chrome.debugger) and Python 3.10 or newer. Used on macOS and Linux. Not on the Chrome Web Store, on purpose: you run the code you can read.

Site scripts

The repository includes example scripts for sites without a usable posting API for individuals: video uploads to several social sites, Discord messages, and a slow, rule-reading queue for Facebook groups. Each takes --draft so you can check everything before it is published.

Your browser, your accounts, your responsibility. Follow each site's terms and automation rules and each community's rules. No spam, mass posting or fake engagement. Tabrelay is not affiliated with any of those sites, scripts break when sites change, and automated use can get an account limited.

Read the full disclaimer.

Free and open source

Tabrelay is free and open source under the MIT licence. Bug reports and ideas are welcome as GitHub issues.