AI Bridge

Manage a Linux machine from an AI chat on your phone or laptop, and continue chats with coding agents (Claude Code, Codex, Cursor) already installed on it.

AI Bridge is a small Python MCP server that gives your MCP client shell commands, files, background jobs, SSH and optional coding agents. The client supplies the AI; no local model or extra API key is needed.

MCP client → HTTPS + token → tunnel → 127.0.0.1:8765 → shell, files, jobs, agents

This is remote admin access. The token grants the service user's access, including root through sudo. Read SECURITY.md before exposing it.

Install

Linux with systemd and Python 3.10+. From the reviewed source folder:

bash install.sh
systemctl status ai-bridge --no-pager
curl --fail http://127.0.0.1:8765/healthz

Then set up HTTPS and your client: setup.

The interactive installer adds local tool preferences to Codex's AGENTS.md and Claude Code's CLAUDE.md: ordinary work on the same machine uses native tools. The preference stays out of shared MCP guidance; chatgpt.com and claude.ai still use the bridge to reach this host. See local agent instructions.

• Normal user: installs as that user; sudo is used when needed.

• Root: offers a dedicated ai-bridge account (recommended) or direct root (high risk). Unattended root install needs --run-as-root.

Related MCP server: Universal Host Manager MCP

Update or remove

• Update: run bash install.sh --update in a host terminal. It builds, shows test progress, activates, restarts, and checks the service. Existing authenticator setup is kept.

• Phone approval: bash install.sh --setup-authenticator handles enrollment and restart.

• Restart: bash install.sh --restart shows the service state until verification succeeds.

• Stage only: bash install.sh --stage builds and tests without changing the running service.

• Remove: bash install.sh --uninstall --dry-run, then bash install.sh --uninstall, from a host terminal (never through the bridge). See full uninstall.

Docs

• Setup: install choices, HTTPS, client connection, settings

• Tools: the 18 tools with examples

• Sudo approval: approve privileged calls on the host or with a phone authenticator

• Operations: deploy, rollback, troubleshooting, uninstall

• Releasing: versions and release steps

• Reliability: limits, logging, containment

• Host configuration: client guidance, resources, prompts

• Instructions guide · Agent session contract

Run the tests with the installed environment:

~/.local/share/ai-bridge/current/venv/bin/python -m unittest discover -s tests

MIT licensed. See LICENSE.