aevra

Current source release: 1.3.0. Standalone browser and desktop source releases: 1.0.0 each.

<div align="center"> <img src="https://raw.githubusercontent.com/the-long-ride/aevra/main/assets/aevra-logo.png" alt="aevra Logo" width="256" />

</div>

aevra is a local MCP execution gateway that lets AI assistants (such as ChatGPT, Claude, and Grok), any AI platform with an MCP connector, and all AI coding agents (such as Cursor, Windsurf, Claude Code, Cline, Roo Code, and Copilot) work directly on your machine: edit files, run commands, manage Git repositories, automate desktop software, drive browsers, and bridge upstream MCP servers under explicit security boundaries.

As a unified MCP gateway, aevra acts as both a secure execution host and an upstream proxy aggregator. It serves 74 built-in system tools while republishing external downstream MCP servers under collision-resistant namespaces (server__tool). When an AI client requests an action, aevra validates the request against your configured capability profile, enforces fine-grained path and command policies, prompts for human approval on sensitive operations, and records each action to a tamper-evident audit log.

It supports any client or platform using the Model Context Protocol (MCP) standard, runs on Windows, macOS, and Linux, and connects over local loopback, private networks, or public tunnels with floating-IP session continuity.

<p align="center"> <img src="https://raw.githubusercontent.com/the-long-ride/aevra/main/assets/aevra-architecture.png" alt="aevra architecture diagram" width="100%" /> </p> <details> <summary><strong>Architecture diagram details (text format)</strong></summary>

Ingress Clients:
  - AI Web Clients & Assistants (ChatGPT, Claude, Grok, Gemini, Langdock, Manus)
  - AI Coding Agents & Other MCP Platforms (Cursor, Windsurf, Claude Code, Cline, Roo Code, any MCP connector)
  - Remote Supervisor Devices (Phones, tablets, secondary browsers accessing Admin Web UI)
                            │
Public MCP Gateway (Port 47830 - Direct HTTPS / Cloudflare / Tailscale / ngrok / SSH)
                            │
  ┌─────────────────────────┴─────────────────────────┐
  │                                                   │
MCP Data Plane (Port 47832)               Admin Control Plane (Port 47831)
aevra Core Daemon                         React Web UI
(policy · sessions · floating-IP continuity (approvals · live activity · settings · MCP upstreams
 · token metering · result shaper)         · token usage analytics · tool surface controls)
  │
Local IPC (named pipe / unix socket)
  │
Execution Worker
  ├─ Filesystem & Git repositories
  ├─ Shell execution & managed background processes
  ├─ Desktop control (Windows UIA · macOS AX · Linux AT-SPI semantic actions)
  ├─ Browser control (Chromium MV3 extension & CDP)
  └─ Upstream MCP proxies & container sandbox

</details>

The central invariant: The Core decides authority. The Worker executes only the exact authority it receives.

---

Local AI agents and one browser extension

Run aevra agent list to see which of Codex, Claude Code, OpenCode and Antigravity Aevra detects, then aevra agent install to connect them: it lists the detected agents and asks to confirm (--yes skips the question). You can also name targets, for example aevra agent install codex or aevra agent install all. stdio is the default; --transport http selects native HTTP for global connections. Add --workspace <name> to connect an agent to one registered workspace only (stdio, no skill). Settings offers the same controls, including a Connect dialog. Each target gets its own credential, and existing gateway approvals and access policy apply through either transport.

Skills live in ~/.agents/skills/aevra, with managed links into agent-specific folders. aevra agent uninstall <target|all> removes owned registration/link resources and revokes credentials. aevra uninstall --purge additionally removes owned service/state resources; user changes and the other product's shared files are preserved. Use --dry-run to inspect an installation or removal first.

A single loaded extension serves both products. Pair with root Aevra's port 47831, or standalone Browser's port 47841, using a fresh code. One server is active at a time. See the local agent guide for transport, shared installation, cleanup and TLS details.

Work alongside your AI agent

Keep using your mouse and keyboard while an agent works through supported background actions in another application or browser tab. Desktop semantic operations address controls through UIA, AX or AT-SPI; browser actions address a selected tab through the extension or CDP. These paths avoid driving the system cursor or typing into whichever application you happen to be using.

For desktop work, prefer desktop_describe(mode:"background") with desktop_invoke, desktop_set_value, desktop_select and desktop_toggle. For browser work, keep the agent pinned to its task tab while you use another tab or application. Coordinate edits to the same document, page or field: background targeting avoids input-device conflicts but does not merge simultaneous edits.

Explicit desktop foreground click/type/key/scroll tools use shared OS input and need a coordinated turn. An application can also change focus or open a modal after a semantic action; a reported focusChanged suspends the desktop lease until a fresh describe. Explicit browser tab-focus commands change the selected tab, and the extension's visible-tab screenshot path requires an active tab rather than activating a background tab silently.

Shared engine, different products: root Aevra and Aevra Desktop use the same canonical native desktop implementation, including the background semantic path. Root runs it through a helper process under gateway policy; standalone runs it in-process under its app allowlist. They have independent sessions, grants and configuration. The common engine does not coordinate competing operations from both hosts on the same target.