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

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.