Local desktop bridge

Bea Bridge

A small, security-conscious server that runs on Bea's Windows PC and gives trusted local tools sandboxed access to files, an allowlisted terminal, and analysis dumps.

This page is a documentation preview. Bea Bridge runs locally - it is not hosted, and nothing on this site can reach Bea's computer.

What it does

A quiet bridge from Bea's PC to the tools she trusts

Bea Bridge is a small local server that runs on Bea's own Windows PC. It gives a local client - Poke, another tool, or a script - careful, sandboxed access to files, a command allowlist, and analysis dumps. It never leaves the machine.

Sandboxed files

List a directory, read a file, write a file - all confined to one allowlisted root folder you choose.

Safe terminal

Run only an explicit allowlist of commands, with timeouts, output caps, and a restricted working directory.

Analysis dumps

Receive and export analysis dumps into a dedicated folder, with size limits on both sides.

WebSocket + MCP

A request/response and streaming channel, plus an optional MCP interface for local agents.

Security model

Built to stay quiet and contained

Local only

Binds to 127.0.0.1. Never exposed to the public internet by default.

Token on every call

Every endpoint needs a bearer token. Tokens are compared in constant time and never logged.

Root allowlist

Paths are resolved against a single root. Traversal and symlink escapes are rejected.

No arbitrary shell

Only allowlisted executables run, as argument lists - never a shell string.

Quick start

Running it on Windows

From PowerShell, inside the project folder:

01  python -m venv .venv
02  .\.venv\Scripts\Activate.ps1
03  pip install -r requirements.txt
04  python -m bea_bridge --generate-token
05  python -m bea_bridge --root C:\bea --token <your-token>

The server listens on http://127.0.0.1:8000 and requires the token on every call. Full setup, troubleshooting, and the security warning live in the project README.

Endpoints

What a client can call

GET/healthStatus and configuration

GET/fs/listList a directory

GET/fs/readRead a file

POST/fs/writeWrite a file

POST/terminal/execRun an allowlisted command

POST/dumps/uploadReceive an analysis dump

GET/dumps/exportExport an analysis dump

WS/wsRequest/response + streaming

A note on this page

This is a preview, not a doorway

What you are reading is a project and documentation preview. Bea Bridge is intended to be run locally on Bea's PC. Nothing hosted here can access her computer, and no hosted deployment can reach it directly. To use the bridge, follow the setup steps above on Bea's own machine.