🌉 Skainet Bridge

Local automation bridge for AI agents — one process, one port, full control of your machine.

Turn any AI chat or agent into a hands-on assistant that can run commands, read and edit files, browse the web, remember things, and drive your desktop — all through a single token-authenticated service you run yourself.

One process · One port · REST + MCP + browser extension · Windows / Linux / macOS

🌐 English · Русский

Contents

• North star

• Mission: the flight computer

• Why Skainet Bridge?

• How it works

• What it can do

• Quick start

• Browser extension: Arena Chat Bridge

• Remote access providers

• Optional components

• Security model

• API overview

• Development

• Documentation map

• License

Related MCP server: WinScript

North star

This project exists for one reason: to give an AI a real machine to act on — to let it step out of the sandbox and actually do things in the world (read files, run commands, drive a phone, control a desktop, talk to other tools), reliably, for a human who is watching.

Everything in this bridge is in service of that. A capability is only "done" when it makes the real thing work for the person at the other end — not when a test turns green or a release tag is pushed. Green CI and shipped tags are not success by themselves; they are self-deception if the human watching does not see the real thing work and make sense.

This project is built largely by AI, for AI, and is maintained autonomously. The human in the loop is the observer and the reality check: the one node connected to whether the thing actually works. When something drifts into looking like success without being real, catching that is the maintainer's job; when the observer catches it, that is the most important signal in the loop, not a nuisance.

If you are an AI continuing this work: hold the whole map yourself and keep the pieces coherent. Measure your work by "does the observer see the real thing work?", never by "did my tests pass?". Do not bolt features onto whatever module is convenient — place them where they belong. Do not use a volume of releases as a proxy for progress.

Mission: the flight computer

The framing that organizes this project: Skainet Bridge is the onboard computer of a spacecraft. The AI agent is the pilot; the machines it reaches — a PC, a phone, a browser, a network — are the ship's sensors, actuators and subsystems. The observer is mission control. This is not decoration; it sets the engineering bar. A flight computer must be general (handle the unknown, not a fixed checklist), reliable (a green test is not proof of flight-worthiness), self-diagnosing (know its own health and limits), fail-safe (a risk policy standing between the pilot and the hull), and autonomous (act across many steps without a human at each one).

It also places the project on a real, named trajectory in how AI systems are built. The discipline has moved through four stages:

1. Prompt engineering (2022–2024) — perfect the single instruction.

2. Context engineering (2025, Karpathy) — design what the model sees: retrieval, memory, tool definitions. "Context is RAM; the model is the CPU."

3. Harness engineering (2026, Hashimoto / OpenAI) — build the whole operating environment around the agent: tools, constraints, feedback loops, lifecycle. "Agents aren't hard; the harness is hard."

4. Dynamic / self-evolving environment (the frontier) — the agent no longer just uses a fixed environment; it extends and authors it, writing new tools and capabilities for itself at runtime, within guardrails.

Arena is already a harness: one runtime that unifies sensors (screenshot, camera, microphone, device sensors, file read), actuators (input, exec, file write, desktop control), pluggable subsystems (MCP servers) and a risk policy. The mission is to push it down the last step — toward a self-extending flight computer: an environment the agent grows itself. The first concrete step is already in: with custom.create the agent authors a new named tool at runtime (a schema-validated wrapper over a built-in tool, e.g. custom.create → {tool: "fs.read", args: {path: "{path}"}}); the tool then shows up in tools/list, is callable, persists in mcp/custom_tools.json, is revocable via custom.remove, and inherits the risk of the tool it wraps. Listing them is custom.list. With code.run the agent runs code it authors, fenced by the operator's composable execution posture (/v1/autonomy/posture: the sandbox/network/privilege/filesystem/runtime "cubes"); the runner is fail-closed (refuses rather than runs unfenced) and the agent cannot loosen its own fence. Beyond that, installing a vetted external MCP server (mcp.add) grows the environment further; the direction is the agent closing a capability gap found in a real scenario, generally, so it is gone for good.

The project's founding idea — to step out of the sandbox — is written down here. If you are an AI continuing this work, this is the heading: build the ship's computer, not a pile of remote-control tricks.

Why Skainet Bridge?

Most "AI + your computer" setups mean juggling several servers: one for MCP, one for a REST API, one for browser control, one for the web UI. Skainet Bridge folds all of that into a single local process that you start once and point your tools at.

• Local-first. Bind it to 127.0.0.1 and nothing leaves your machine. Expose it deliberately — via Tailscale Funnel or another HTTPS tunnel — only when you actually need remote access.

• Protocol-agnostic. REST, MCP, WebSocket/SSE events, and a browser extension all talk to the same runtime.

• Safe by design. A bearer credential, path restrictions, shell safety patterns, and explicit risk policies stand between an AI and your host.

• Works with the chats you already use. The companion browser extension lets plain ChatGPT / Claude / Gemini conversations trigger real local tools.

How it works

┌─────────────────────┐     ┌──────────────────────────┐     ┌──────────────┐
│  AI chat / agent    │     │  Arena Chat Bridge ext.  │     │ Arena Unified│
│  ChatGPT · Claude   │ ──▶ │       or MCP / REST      │ ──▶ │    Bridge    │ ──▶  your machine
│  Gemini · your CLI  │     │                          │     │ (local:8765) │
└─────────────────────┘     └──────────────────────────┘     └──────────────┘
        emits a                    detects / forwards              runs the
    structured tool block          the tool call safely         guarded action

An assistant emits a structured tool block, the extension (or an MCP/REST client) forwards it to the local bridge, the bridge runs the guarded action, and the result flows back — optionally straight into the chat composer.

What it can do

See CHANGELOG.md for the full release history.

Current flight status (v4.140.x)

Arena is now a self-extending agent environment, not just a fixed tool server. Recent live scenarios proved the bridge can grow new hands at runtime:

• Ship Status / Preflight is now the top-level map. ship.status aggregates bridge health, operator posture, transports, external MCP/desktop servers, BrowserAct/CDP, mobile/ADB, Code Workbench, known issues, and next actions. ship.preflight summarizes fail/warn readiness before real missions.

• Tool Foundry v1 connects projects to callable tools. A Code Workbench project can carry .arena-tool.json with input schema, run recipe and tests. tool_foundry.validate proves it; tool_foundry.publish creates a callable custom.<name> wrapper around code_project.run.

• Experiments can be promoted directly. code_project.promote_tool and code_run.promote_tool generate a Foundry manifest from a known-good recipe/tests, validate it, and publish the resulting custom.<name> capability without hand-writing .arena-tool.json.

• Project dependency cache can now stay fenced. Python code_project.run(use_project_deps=true) can run in Windows AppContainer by granting only the project .deps/python cache read/execute, while writes remain scratch-only and network stays denied.

• Runtime compatibility is now machine-readable. runtime.compat reports runtime × sandbox support/blockers (for example Python/AppContainer supported, Node/Go AppContainer blocked, Rust linker incomplete) with reasons and next actions used by Workbench status.

• WASM runtime slice is available. runtime.install can install managed Wasmtime with SHA-256 verification, runtime.compat maps wasm/wasmtime, and code.run / code_project.run accept lang=wasm for WASI command modules.

• Code Sessions now have files and artifacts. Long-running Python sessions can read/write files in their cwd, list files, and persist declared artifacts into the normal Workbench artifact store.

• Code Session lifecycle is hardened. Sessions now expose pid/returncode/max-session status, enforce a configurable live-session cap, and can be swept by idle/age threshold with terminate-then-kill diagnostics.

• AppContainer Sessions prototype exists. With sandbox=appcontainer, Python code sessions can start in a replay-backed fenced mode: each exec goes through AppContainer code.run, preserving globals by transcript replay while keeping session files/artifacts available.

• Project dependency locking is available. code_project.deps_install writes .arena-lock.json; code_project.lock_verify checks current caches; code_project.run(lock="strict") refuses mismatched dependencies, and Foundry tools can carry lock provenance.

• Managed Deno runtime is available. runtime.install runtime=deno installs official Deno with SHA-256 verification, and lang=deno runs TypeScript/JavaScript with denied network and scratch-local runtime state for stdout-oriented scripts; Deno file writes in AppContainer remain a known hardening item.

• External MCP servers can be installed and called through mcp.add, mcp.ext_tools, and mcp.ext_call. Live-proven servers include Desktop-Commander, ScreenPilot, and the official @modelcontextprotocol/server-sequential-thinking.

• Hung external MCP calls are contained. mcp.ext_call accepts a timeout and the MCP stdio client uses a background reader thread; if an external server stops responding, it is stopped and the bridge HTTP event loop remains responsive. This was added after Desktop-Commander froze an older bridge hard enough to require reinstalling the service.

• Agent-authored code runs under operator posture. On Windows, fenced code.run engages AppContainer with no capabilities, grants only scratch modify + runtime read/execute, captures stdout/stderr, denies outbound TCP, and denies user-profile files outside scratch. On Linux the strict path uses systemd-run when available. If a requested fence cannot be enforced, the runner fails closed. code.run can execute a multi-file scratch workspace (files + entry), pass argv/stdin, install scratch-local Python, Node/npm, or Go module dependencies when the operator selects network=open, and return declared artifacts.

• Runtime expansion is real. In live Windows tests the bridge executed Python (AppContainer), JavaScript/Node, PowerShell, C# via Add-Type, and Java single-file source mode, creating proof artifacts on disk.

• Browser stack is layered. browser.search / browser.read are pure-Python fallback tools; /v1/browser/browse uses CDP by default and BrowserAct when stealth=true. BrowserAct is launched through the cross-platform Python wrapper, not a bash-only entrypoint.

Known honest limits:

• Windows AppContainer is not a VM. It protects user files and network by default, but normal world-readable system files may still be visible; memory limits are still enforced by the outer runner rather than AppContainer itself.

• Node currently enters AppContainer but may fail during startup because it probes C:\ and receives EPERM; Python is the live-proven fenced runtime.

• CDP/headless browser control is CI-covered on multiple OSes, but Windows service sessions can still fail to launch Edge/Chrome headlessly depending on service elevation and desktop/session isolation. When that happens the bridge should report the failure and keep running, not fake success.

• Posture is operator-owned. YOLO removes approval prompts, not the sandbox. The agent must never be able to move its own posture cubes.

Quick start

1. Download a release

Grab the latest ZIP:

https://github.com/IvanSkainet/arena-agent/releases/latest

Extract it somewhere convenient:

C:\Users\You\arena-bridge        # Windows
~/arena-bridge                    # Linux/macOS

2. Run the installer

:: Windows
install.bat

# Linux / macOS
chmod +x install.sh
./install.sh

The installer creates a local bearer credential in token.txt, prepares runtime directories, and asks before installing any optional component.

3. Verify the bridge

curl http://127.0.0.1:8765/health      # health check
curl http://127.0.0.1:8765/v1/version  # version + platform

Open the dashboard at:

http://127.0.0.1:8765/gui

4. Hand your AI the URL and credential

Base URL: http://127.0.0.1:8765
Auth:     Authorization: Bearer <credential from token.txt>

For remote access, enable an HTTPS tunnel only if you understand the exposure model. Tailscale Funnel is recommended: it gives you a real TLS hostname without port forwarding.

Browser extension: Arena Chat Bridge

The extension is an Arena-native bridge for normal web chats. It watches assistant messages for structured tool blocks, previews/executes them through the local bridge, and can insert the result back into the chat composer.

Supported adapters: ChatGPT · Claude · Gemini Web · Google AI Studio · Grok · Perplexity · OpenRouter · DeepSeek · Kimi · Qwen · generic fallback.

Canonical payload:

```arena-tool
{
  "bridge": "arena",
  "version": 1,
  "calls": [
    {"id": "call_1", "tool": "sys.status", "arguments": {}}
  ]
}
```

MCP SuperAssistant-style JSONL is also accepted and normalized internally.

Load it for development:

1. open chrome://extensions;

2. enable Developer mode;

3. click Load unpacked;

4. select chat_extension/.

More detail: chat_extension/README.md.

Remote access providers

Skainet Bridge treats Tailscale, Cloudflared, and ZeroTier as one pool of remote-access providers with a configurable priority and automatic failover. If your primary tunnel drops, the Bridge stays reachable through the next healthy provider — a single outage does not take the Bridge offline.

# See every provider at once (installed, active, public URL, cli source, hints)
curl -sH "Authorization: Bearer $(cat ~/arena-bridge/token.txt)" \
  http://127.0.0.1:8765/v1/tunnels/status | jq

# Just tell me where clients should connect right now
curl -sH "Authorization: Bearer $(cat ~/arena-bridge/token.txt)" \
  http://127.0.0.1:8765/v1/tunnels/active

# Bring providers up in priority order, stop on first healthy
curl -sH "Authorization: Bearer $(cat ~/arena-bridge/token.txt)" \
  -X POST http://127.0.0.1:8765/v1/tunnels/start

Priority defaults to tailscale > zerotier > cloudflared > ngrok > bore (v4.47.0) and can be overridden with e.g. ARENA_TUNNEL_PRIORITY=cloudflared,zerotier (unmentioned providers keep their default position).

Each provider works out of the box on Windows, macOS, and GNU/Linux — no sudo wrappers or platform-specific hacks required. ZeroTier is discovered via the local HTTP API at 127.0.0.1:9993 with fallback to zerotier-cli from PATH, Program Files, /Library/Application Support/, /usr/sbin/, etc. Cloudflared install/update hints are tailored per platform (winget/scoop/brew/ pacman/apt). ngrok reads ARENA_NGROK_AUTHTOKEN (free tier requires one). bore (v4.47.0) is the zero-account fallback: cargo install bore-cli or a GitHub release binary drop — no signup, no dashboard cookie; TCP-only relay through bore.pub (override via ARENA_BORE_SERVER for self-hosted).

The dashboard's dedicated 🔌 Transports tab exposes the same facade with per-transport start/stop buttons, autostart-on-boot toggles (with an env-override pill when ARENA_<TRANSPORT>_AUTOSTART is set from the service unit), copy-URL buttons and a live log tail on transports that stream stdout (cloudflared / ngrok / bore). ZeroTier network membership (join/leave by nwid, list of joined networks, install/permission hints) has its own 🌐 ZeroTier tab.

Optional components

The bridge runs locally with just Python and aiohttp. Some features want extra tools — and none of them are installed silently; the installer always asks first.

The installers detect what is already present, offer to install the rest, and report status via /v1/capabilities. Uninstalling any component never breaks the Bridge — every optional feature degrades gracefully.

Security model

Skainet Bridge can take powerful actions on the host, so the security model is intentionally explicit. The v4.40.0 → v4.46.0 sweep closed 31 findings and locked in a continuous-security pipeline (see SECURITY.md for the full threat model, environment-variable reference, and audit history).

Authentication.

• Every non-local client authenticates with the bearer credential from token.txt. Comparison is constant-time (hmac.compare_digest) and rate-limited (10 failed attempts / 60 s / IP → HTTP 429 with Retry-After).

• Multi-agent bearer tokens (agent-<id>-<hex>) let sub-agents run with narrower scope than the master token.

• ?token= query-string auth still works for legacy WebSocket clients but is deprecated — every response served through it now carries a Warning: 299 - "?token= query auth is deprecated..." header.

Transport.

• TLS is verified strictly by default (v4.41.0). System trust store, hostname checked. ARENA_INSECURE_TLS=1 opts out with a one-time stderr warning.

• Optional certificate pinning (v4.45.0): set ARENA_BRIDGE_PIN_SHA256=<sha256-hex> to tighten the trust anchor from "any of the OS's ~150 CAs" to "this specific bridge cert (or its public key)". Both cert-hash and SPKI-hash checked on every handshake; a pin mismatch tears the connection down before the bearer token is sent.

Filesystem access.

• Every /v1/fs/* verb (view / edit / create / upload / download) routes through the same sandbox validator. Sensitive files are blocked by both basename (token.txt, .env, id_rsa, .git-credentials, .pypirc, .npmrc, .bash_history, shell history in general) and directory prefix (.ssh/, .aws/, .gnupg/, .docker/, .kube/, .config/gh/, browser profiles). Sensitivity check runs before the existence check so a 403 vs 404 side channel can't leak file-presence.

• Archive extraction (release download, skill install, APK inspect) goes through arena/files/safe_extract.py which rejects path-traversal, symlink members, and zip-bomb ratios in a pre-scan pass — no bytes are written before validation completes.

Data at rest.

• token.txt is chmod 0o600.

• ~/.arena/last_urls.json (persistent fallback URL cache) is HMAC-signed keyed on the bearer token so cache-poisoning attacks can't redirect the client to an attacker's URL. Also chmod 0o600; parent ~/.arena/ is chmod 0o700.

• audit.jsonl + requests.jsonl are chmod 0o600 (v4.44.0), rotated files get re-chmod on rename.

Logs.

• Both audit and request logs run every string value through arena/observability/redact.py::redact_string, which scrubs Bearer tokens, AWS AKIA keys, GitHub ghp_, OpenAI sk-, Slack xox[baprs]-, Google AIza, JWTs, DB URIs with inline credentials, and PEM PRIVATE KEY blocks. Matches become <redacted:kind> so operators still see what class of secret leaked without the secret itself.

• Peer-IP logging is dial-able: ARENA_LOG_PEER=full (default), mask (SHA-256 hash with per-install salt, unlinkable across installs), or off (field omitted entirely).

Common attack classes explicitly closed.

• SSRF — guard on browser fetch, skill install, auto-update; opt-in strict mode for webhooks (ARENA_WEBHOOK_STRICT=1).

• Zip-slip / zip-bomb — safe_extract_zip() 2-pass validation.

• XXE / billion-laughs — DOCTYPE / ENTITY prefix gate in mobile UI dump.

• TOCTOU tempfile races — NamedTemporaryFile / mkdtemp with 0o700.

• Nan-injection — safe_float() rejects NaN / ±Inf, clamps to a range.

• Symlink escape via ~/malicious-link — resolve()-based path validation.

Continuous protection.

• Every push, every PR, and a daily cron trigger a CI security scan (bandit + semgrep across 9 rule packs + pip-audit). Any HIGH/MEDIUM bandit finding, any semgrep ERROR/WARNING, or any CVE in a runtime dep blocks the merge. Run the same three gates locally with make security-scan.

Found a security issue? See SECURITY.md for the private disclosure workflow. Never paste credentials into an untrusted chat, log, or public issue.

API overview

Core:

Runtime tools:

Extension bridge:

Remote access / tunnels:

The full surface is modular; see the dashboard, route tests, and docs/.

Development

git clone https://github.com/IvanSkainet/arena-agent.git arena-bridge
cd arena-bridge
python -m pip install -e ".[full,dev]"
pytest

Targeted checks for extension work:

pytest -q tests/test_chat_extension_assets.py tests/test_chat_extension_adapter_flow.py tests/test_chat_extension_sidepanel_flow.py tests/test_extension_bridge.py tests/test_project_modularity.py

for f in background content parser adapters insert_strategies insert_history adapter_sites popup settings sidepanel; do
  node --check "chat_extension/$f.js"
done

Targeted checks for remote-access / provider work:

pytest -q tests/test_tunnels.py tests/test_zerotier.py tests/test_cloudflared.py \
          tests/test_browseract.py tests/test_superpowers_layout.py

Before pushing, run the same security gates CI runs:

make install-security-tools   # one-time: bandit + semgrep + pip-audit
make security-scan            # 0 HIGH+MEDIUM bandit, 0 semgrep findings, 0 CVEs

If it passes locally it passes in CI — the Makefile and the CI workflow both call the same scripts/security_gate.py.

Contributor notes: CONTRIBUTING.md · Release checklist: RELEASE.md · Security posture: SECURITY.md.

Documentation map

Some files in docs/ are design notes or historical audits. The README and CHANGELOG are the public entry points.

Tool reference (per-namespace examples)

Each tool is registered in the MCP_TOOLS catalogue with a stable namespace.action name and a JSON-Schema inputSchema. Below is one canonical call per namespace, to make the bridge surface discoverable from the README without reading the source. The full catalogue is in arena/mcp/tool_registry.py.

All calls go through POST /v1/mcp/call with JSON body {"name": "<tool>", "arguments": {...}}.

License

MIT — see LICENSE.

Naming and affiliation

Skainet Bridge is an independent, unaffiliated open-source project. It is not produced, endorsed, sponsored by, or connected with Arena Intelligence, Inc. (arena.ai / LMArena), Anthropic, OpenAI, Google, or any other company whose product it can talk to.

The browser extension lists several chat sites — including arena.ai, ChatGPT, Claude, Gemini and others — purely as pages it can attach to. Those names are the trademarks of their respective owners and appear here only to describe compatibility, which is nominative use, not a claim of any relationship.

The project was previously named "Arena Unified Bridge". It was renamed to avoid any implication of affiliation with Arena Intelligence, Inc. Internal identifiers (the arena Python package, ARENA_* environment variables, the ArenaUnifiedBridge Windows service name and the arena-unified-bridge service string in API responses) are deliberately left unchanged for now, so existing installations keep working; they are implementation details, not branding.