feat(serve): add remote browser control over TCP with token auth

Exposes a local browser over a TCP socket so remote machines can
  control it using the same CLI and Python API. Token auth (auto-generated
  via secrets.token_urlsafe) is on by default; --no-auth disables it.
  Profile routing via _route message field lets clients target specific
  browser instances on the remote host. BROWSER_CLI_PROFILE is forwarded
  automatically so --browser flag works transparently over remote.
  - browser-cli serve [--host] [--port] [--token] [--no-auth]
  - browser-cli --remote HOST:PORT --token TOKEN <command>
  - BrowserCLI(remote="host:port", token="...").tabs_list()

browser_cli/__init__.py

@@ -33,16 +33,22 @@ class BrowserCounts:
 
 
 class BrowserCLI:
-    def __init__(self, browser: str | None = None):
+    def __init__(self, browser: str | None = None, remote: str | None = None, token: str | None = None):
         """
         Args:
             browser: Profile alias to target. Required when multiple browser
                      instances are active. Equivalent to ``--browser`` on the CLI.
+            remote: Connect to a remote browser exposed via ``browser-cli serve``.
+                    Format: ``"host:port"`` (e.g. ``"192.168.1.10:8765"``).
+                    When set, ``browser`` is ignored.
+            token: Auth token for the remote serve instance.
         """
         self._browser = browser
+        self._remote = remote
+        self._token = token
 
     def _cmd(self, command: str, args: dict | None = None):
-        return send_command(command, args, profile=self._browser)
+        return send_command(command, args, profile=self._browser, remote=self._remote, token=self._token)
 
     def _multi_browser_targets(self):
         if self._browser is not None:

browser_cli/cli.py

@@ -24,6 +24,7 @@ from browser_cli.commands.search import search_group
 from browser_cli.commands.page import page_group
 from browser_cli.commands.storage import storage_group
 from browser_cli.commands.cookies import cookies_group
+from browser_cli.commands.serve import cmd_serve
 from browser_cli.client import (
     send_command,
     BrowserNotConnected,
@@ -164,14 +165,26 @@ def _print_version(ctx, param, value):
     "--browser", default=None, metavar="ALIAS",
     help="Browser profile alias to target (required when multiple browsers are active).",
 )
+@click.option(
+    "--remote", default=None, metavar="HOST:PORT",
+    help="Connect to a remote browser exposed via 'browser-cli serve'.",
+)
+@click.option(
+    "--token", default=None, metavar="TOKEN",
+    help="Auth token for the remote browser-cli serve instance.",
+)
 @click.pass_context
-def main(ctx, browser):
+def main(ctx, browser, remote, token):
     """Control your running browser from the terminal via a Chrome extension."""
     ctx.ensure_object(dict)
     ctx.obj["browser"] = browser
     ctx.obj["browser_explicit"] = browser is not None
     if browser:
         os.environ["BROWSER_CLI_PROFILE"] = browser
+    if remote:
+        os.environ["BROWSER_CLI_REMOTE"] = remote
+    if token:
+        os.environ["BROWSER_CLI_TOKEN"] = token
 
 
 # ── Sub-command groups ─────────────────────────────────────────────────────────
@@ -186,6 +199,7 @@ main.add_command(search_group)
 main.add_command(page_group)
 main.add_command(storage_group)
 main.add_command(cookies_group)
+main.add_command(cmd_serve)
 
 
 # ── clients ────────────────────────────────────────────────────────────────────

browser_cli/client.py

@@ -98,28 +98,50 @@ def _resolve_socket(profile: str | None = None) -> str:
     )
 
 
-def send_command(command: str, args: dict | None = None, profile: str | None = None) -> Any:
+def send_command(command: str, args: dict | None = None, profile: str | None = None, remote: str | None = None, token: str | None = None) -> Any:
     """Send a command to the browser and return the response data."""
-    sock_path = _resolve_socket(profile)
+    remote_endpoint = remote or os.environ.get("BROWSER_CLI_REMOTE")
+    resolved_token = token or os.environ.get("BROWSER_CLI_TOKEN")
     msg = {
         "id": str(uuid.uuid4()),
         "command": command,
         "args": args or {},
     }
+    if remote_endpoint:
+        if resolved_token:
+            msg["token"] = resolved_token
+        route_profile = profile or os.environ.get("BROWSER_CLI_PROFILE")
+        if route_profile:
+            msg["_route"] = route_profile
     payload = json.dumps(msg).encode("utf-8")
     framed = struct.pack("<I", len(payload)) + payload
 
     try:
-        if is_windows():
+        if remote_endpoint:
+            host, _, port_str = remote_endpoint.rpartition(":")
+            if not host or not port_str:
+                raise BrowserNotConnected(f"Invalid remote endpoint '{remote_endpoint}': expected host:port")
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+                sock.connect((host, int(port_str)))
+                sock.sendall(framed)
+                response = _recv_all(sock)
+        elif is_windows():
+            sock_path = _resolve_socket(profile)
             with PipeClient(sock_path, family="AF_PIPE") as conn:
                 conn.send_bytes(payload)
                 response = conn.recv_bytes()
         else:
+            sock_path = _resolve_socket(profile)
             with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
                 sock.connect(sock_path)
                 sock.sendall(framed)
                 response = _recv_all(sock)
     except (FileNotFoundError, ConnectionRefusedError, OSError):
+        if remote_endpoint:
+            raise BrowserNotConnected(
+                f"Cannot connect to remote browser at {remote_endpoint}.\n"
+                "Make sure browser-cli serve is running on the remote host."
+            )
         profile_hint = f" (profile: {profile})" if profile else ""
         raise BrowserNotConnected(
             f"Cannot connect to browser{profile_hint}.\n"

browser_cli/commands/serve.py

@@ -0,0 +1,153 @@
+import threading, secrets, socket, struct, click, json, sys
+from rich.console import Console
+from datetime import datetime
+
+console = Console()
+
+def _recv_exact(sock:socket.socket, n:int) -> bytes:
+  buf = b""
+  while len(buf) < n:
+    chunk = sock.recv(n - len(buf))
+    if not chunk:
+      raise ConnectionError("Connection closed")
+    buf += chunk
+  return buf
+
+def _log(addr:tuple, command:str, profile:str|None, status:str, error:str|None=None) -> None:
+  ts = datetime.now().strftime("%H:%M:%S")
+  addr_str = f"{addr[0]}:{addr[1]}"
+  profile_str = f"[dim]{profile}[/dim] " if profile else ""
+  if error:
+    console.print(f"[dim]{ts}[/dim] {addr_str} {profile_str}[cyan]{command}[/cyan] [red]{status}[/red] {error}")
+  else:
+    console.print(f"[dim]{ts}[/dim] {addr_str} {profile_str}[cyan]{command}[/cyan] [green]{status}[/green]")
+
+def _proxy_request(client_sock:socket.socket, addr:tuple, profile:str|None, server_token:str|None) -> None:
+  from browser_cli.client import _resolve_socket, BrowserNotConnected
+  from browser_cli.platform import is_windows
+
+  try:
+    header = _recv_exact(client_sock, 4)
+    msg_len = struct.unpack("<I", header)[0]
+    payload = _recv_exact(client_sock, msg_len)
+  except (ConnectionError, OSError):
+    return
+
+  def _send_error(msg_id, msg:str) -> None:
+    err = json.dumps({"id": msg_id, "success": False, "error": msg}).encode()
+    try:
+      client_sock.sendall(struct.pack("<I", len(err)) + err)
+    except OSError:
+      pass
+
+  try:
+    msg = json.loads(payload)
+  except (json.JSONDecodeError, ValueError):
+    _send_error(None, "invalid JSON")
+    _log(addr, "?", None, "ERROR", "invalid JSON")
+    return
+
+  msg_id = msg.get("id")
+  command = msg.get("command", "?")
+
+  if server_token is not None:
+    if msg.get("token") != server_token:
+      _send_error(msg_id, "unauthorized: invalid or missing token")
+      _log(addr, command, None, "DENIED", "bad token")
+      return
+
+  resolved_profile = msg.get("_route") or profile
+
+  strip = {"token", "_route"}
+  if strip & msg.keys():
+    clean_payload = json.dumps({k: v for k, v in msg.items() if k not in strip}).encode()
+    clean_header = struct.pack("<I", len(clean_payload))
+  else:
+    clean_payload = payload
+    clean_header = header
+
+  try:
+    sock_path = _resolve_socket(resolved_profile)
+  except BrowserNotConnected as e:
+    _send_error(msg_id, str(e))
+    _log(addr, command, resolved_profile, "ERROR", "browser not connected")
+    return
+
+  try:
+    if is_windows():
+      from multiprocessing.connection import Client as PipeClient
+      with PipeClient(sock_path, family="AF_PIPE") as pipe:
+        pipe.send_bytes(clean_payload)
+        resp = pipe.recv_bytes()
+      client_sock.sendall(struct.pack("<I", len(resp)) + resp)
+    else:
+      with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as local:
+        local.connect(sock_path)
+        local.sendall(clean_header + clean_payload)
+        resp_header = _recv_exact(local, 4)
+        resp_len = struct.unpack("<I", resp_header)[0]
+        resp_payload = _recv_exact(local, resp_len)
+      client_sock.sendall(resp_header + resp_payload)
+
+    resp_data = json.loads(resp_payload if not is_windows() else resp)
+    if resp_data.get("success", True):
+      _log(addr, command, resolved_profile, "OK")
+    else:
+      _log(addr, command, resolved_profile, "ERROR", resp_data.get("error", ""))
+  except OSError as e:
+    _send_error(msg_id, str(e))
+    _log(addr, command, resolved_profile, "ERROR", str(e))
+
+def _handle_client(client_sock:socket.socket, addr:tuple, profile:str|None, server_token:str|None) -> None:
+  with client_sock:
+    _proxy_request(client_sock, addr, profile, server_token)
+
+@click.command("serve")
+@click.option("--host", default="127.0.0.1", show_default=True, help="Address to bind.")
+@click.option("--port", default=8765, show_default=True, type=int, help="TCP port to listen on.")
+@click.option("--token", default=None, metavar="TOKEN", help="Auth token (auto-generated if omitted).")
+@click.option("--no-auth", is_flag=True, default=False, help="Disable token authentication.")
+@click.pass_context
+def cmd_serve(ctx, host, port, token, no_auth):
+  """Expose this browser over TCP so remote hosts can control it."""
+  profile = ctx.obj.get("browser") if ctx.obj else None
+
+  if host in ("0.0.0.0", "::"):
+    console.print("[yellow]Warning:[/yellow] Binding to all interfaces — anyone who can reach this port controls your browser.")
+
+  if no_auth:
+    server_token = None
+  else:
+    server_token = token or secrets.token_urlsafe(32)
+
+  server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+  server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+  try:
+    server.bind((host, port))
+  except OSError as e:
+    console.print(f"[red]Cannot bind to {host}:{port}:[/red] {e}")
+    sys.exit(1)
+  server.listen(16)
+
+  browser_hint = f" (browser: {profile})" if profile else ""
+  console.print(f"[green]Serving browser{browser_hint} →[/green] [cyan]{host}:{port}[/cyan]")
+
+  if server_token:
+    console.print(f"  Token:  [bold yellow]{server_token}[/bold yellow]")
+    console.print(f"  CLI:  [dim]browser-cli --remote {host}:{port} --token {server_token} tabs list[/dim]")
+    console.print(f"  Python: [dim]BrowserCLI(remote=\"{host}:{port}\", token=\"{server_token}\").tabs_list()[/dim]")
+  else:
+    console.print(f"  CLI:  [dim]browser-cli --remote {host}:{port} tabs list[/dim]")
+    console.print(f"  Python: [dim]BrowserCLI(remote=\"{host}:{port}\").tabs_list()[/dim]")
+    console.print("[yellow]  Auth disabled (--no-auth)[/yellow]")
+
+  console.print("Ctrl-C to stop.\n")
+
+  try:
+    while True:
+      conn, addr = server.accept()
+      threading.Thread(target=_handle_client, args=(conn, addr, profile, server_token), daemon=True).start()
+  except KeyboardInterrupt:
+    console.print("[yellow]Stopped.[/yellow]")
+  finally:
+    server.close()