arena-bridge

Let a web AI agent operate your own authorized VPS, Mac/Linux and Android Termux devices over MCP / HTTP. The main Bridge token is a remote-control credential. Give it only to trusted agents.

AI agent ── HTTPS ──► VPS hub ──► container workspace
                             ◄── Mac / Termux agents dial out (no public device IP)

Fresh install: clone and deploy

Requirements: a Linux VPS, a domain pointed to it, sudo, Python 3 and curl. The installer asks for approval before installing Docker. It reuses existing nginx if present, or runs Caddy for automatic HTTPS. Configure DNS and allow TCP ports 80/443 before starting.

git clone https://github.com/AI-modelsAPI/arena-bridge.git
cd arena-bridge
sudo bash deploy-vps.sh

On first run, enter your public domain and an unlock password of at least 16 characters. By default the installer registers mac,android; to use different names, initialize the config before the first deploy:

python3 scripts/init-config.py --host bridge.example.com --devices laptop,phone
sudo bash deploy-vps.sh

The initializer generates a random main token, separate device tokens and a salted scrypt password hash in a private 0600 .env. It never overwrites an existing .env or prints secrets. If you bring your own .env, ensure mode 0600. Public /health returns only { "ok": true }.

Add your devices

On the VPS, in a private terminal, generate an installer command scoped to each device:

sudo bash show-setup.sh mac
sudo bash show-setup.sh android

Run each output command on that device. It contains the device's secret, so do not share it publicly. Mac/Linux requires Node.js >=22. For Android, use Termux from F-Droid/GitHub, first run pkg install -y nodejs-lts curl, then termux-setup-storage if you need shared files. Termux:Boot and disabling battery optimization help keep it online. The generated installer is saved with 0600 permissions and removed after success. Review downloaded scripts before executing if appropriate; device files live in ~/.arena-device/.

On the VPS, generate the short prompt for a trusted web AI agent:

sudo bash show-setup.sh --prompt

This prompt contains the main token. Never commit or post it publicly. MCP clients can instead use https://your-host/mcp with a Bearer token. Authenticated /devices reports live connections.

Related MCP server: agentic-remote-pc

Permissions, limits and safety

• While locked, only non-sensitive file reads and directory listings inside authorized directories, plus system info, are allowed. Content search, deletes, arbitrary shell/process access, credential reads and third-party MCP tools require unlock (15 minutes by default). See policy.json.

• Every device has a separate credential that cannot use the main API. WebSocket device authentication does not put tokens in URLs. Desktop Commander is no longer installed or enabled by default.

• Binary files are limited to ~8 MiB per call; HTTP/WS requests are capped at 16 MiB. There is no chunked upload. Side-effecting GET /exec and GET /call have been removed: use POST/MCP.

• This policy is a defense against accidents, not an adversarial OS sandbox. Processes started while unlocked can continue after relocking. See SECURITY.md for remaining risks. Do not mount the host Docker socket.

• Protect the VPS .env and device ~/.arena-device/env. Only print device install commands and AI prompts in trusted terminals.

Already running the old version? Migrate first

This release is incompatible with plaintext UNLOCK_PASSWORD, shared client/device credentials and old device agents. Do not merely git pull and restart: the hub may refuse to start and devices will disconnect. Back up .env, policy.json and the Docker /data volume; generate UNLOCK_PASSWORD_HASH and DEVICE_TOKENS_JSON, remove the plaintext secret, and reinstall Mac/Termux agents during a maintenance window. An existing volume may need its owner changed to UID 1000. See .env.example, rehearse in staging, and keep a rollback copy. The three-command quickstart above is for new deployments only and never overwrites an existing configuration.

Run npm ci && npm test on Node 22. The legacy Mac-as-hub service scripts have not been migrated; use the VPS Docker deployment for production. MIT licensed.