aevra

aevra is a secure bridge that lets AI assistants like ChatGPT, Claude, and Grok actually do things on your computer — read and write files, run commands, manage code, search your workspace, and interact with external tools — all while keeping you in full control of what they can and cannot touch.

Think of it as a smart gatekeeper that sits on your machine. When an AI assistant wants to take an action, aevra checks whether it is allowed, asks for your approval when needed, records everything it does, and blocks anything that looks dangerous. You decide the rules; the AI follows them.

It works with any AI tool that supports the Model Context Protocol (MCP) standard, runs on Windows, macOS, and Linux, and can be reached securely from anywhere — your local network, a public tunnel, or behind a firewall.

Internet / AI Web Client / Admin Browser
        │
Public Gateway (127.0.0.1:47830 - HTTPS/HTTP)
(Direct HTTPS / Local / Cloudflare / ngrok / Caddy / Tailscale / FRP / SSH)
        │
 ┌──────┴─────────────────────────────────┐
 │                                        │
127.0.0.1:47832 (HTTPS)                  127.0.0.1:47831 (HTTPS)
MCP Data Plane ── aevra Core Daemon      Admin Control Plane ── React Web UI
(policy · sessions · approvals · audit)  (credentials auth · management modals)
        │
named pipe / unix socket (IPC)
        │
Execution Worker (filesystem · git · commands · sandbox · processes · hooks)

The Central Invariant: The Core decides authority. The Worker executes only the exact authority it receives.

---

What Makes aevra Different?

• Fast Lane Batch Operations & High Performance: First-class file_read_many, file_write_many, and command_run_many batch tools that streamline model tool execution with bounded concurrency, parallel regex search (search), and zero heavy runtime overhead.
• Host System Capabilities Detection: Non-blocking host environment probing that discovers 11 toolchain categories (Git, Node, Python, .NET, Rust, Go, JVM, Ruby, PHP, C/C++, Docker/Podman) and resolves recommended shells (pwsh, powershell, cmd, bash, zsh, sh) automatically.
• Zero-Trust Security & Data Isolation: Central SecurityGuard resource boundary with automatic SECRET denial, SENSITIVE data masking, real-time DLP redaction, and in-depth protection against symlink and hard-link alias attacks.
• Configurable Local Transport & Runtime Validation: Support for HTTPS and HTTP loopback gateway protocols with strict internal HTTPS isolation and active runtime transport security checks.
• Native Cross-Platform Support: First-class citizen on Windows (Scheduled Tasks, named pipes, DPAPI), Linux (systemd --user, unix domain sockets, Secret Service), and macOS (LaunchAgents, Keychain).
• Granular Control & Step-Up Approvals: Multi-tier capability profiles (Minimal, Read-Only, Safe Dev, Power Dev, Full Access, Custom), human-in-the-loop interactive approvals, and policy.critical.alwaysConfirm for sensitive operations.
• Durable Process Lifecycle & Recovery: Named managed background processes (process_start, process_wait, process_logs) with detached completion sidecars, journaled change sets with rollback, and safe 3-way auto-merging for non-conflicting concurrent edits.
• Provider-Neutral Ingress: Run directly via built-in self-signed Direct HTTPS, Cloudflare Access tunnels, managed ngrok, Caddy, Tailscale Funnel, FRP, or reverse SSH with full OAuth 2.0 / PKCE authentication.
• OAuth Connection Continuity: Short-lived access credentials and rotating refresh families reconnect to the same durable logical connection while keeping MCP sessions and workspace leases bounded.

---

Core Features

• 40 Discoverable MCP Tools & Fast Lane Interfaces: Streamlined public toolset featuring batch file reads, mutations, command execution, workspace management, Git operations, durable processes, and change sets (with singular primitives safely delegated internally).
• Host System Capabilities & Status: MCP aevra_status exposes host toolchain snapshots, available shells, and execution defaults directly to models and the Admin UI.
• Dynamic Resources & Instruction Prompts: Serves context files seamlessly via MCP resources (aevra://skill/<source>/<name>) and instruction prompts (aevra-instructions parsed from AGENTS.md / CLAUDE.md).
• React 19 Admin Dashboard: Single-page dark theme dashboard featuring live System Capabilities breakdown, Transport Validation status, real-time MCP activity monitoring with sanitized payloads, and interactive runtime modals.
• Out-of-Process Worker Sandbox: Execution worker runs in an isolated child process communicating over authenticated local IPC, with Docker and Podman container sandboxing support.

---

Quick Onboard Installation

Install aevra globally via npm and start the gateway on your operating system:

Windows (PowerShell)

# 1. Install aevra globally
npm install -g @the-long-ride/aevra@latest

## Choose 2.1 or 2.2:

# 2.1 Configure admin credentials for User scope - Recommend for future use with only aevra start
[System.Environment]::SetEnvironmentVariable('AEVRA_USERNAME', 'admin', 'User')
[System.Environment]::SetEnvironmentVariable('AEVRA_PASSWORD', 'YourSecurePassword', 'User')

# 2.2. Apply to current session only
# $env:AEVRA_USERNAME = 'admin'
# $env:AEVRA_PASSWORD = 'YourSecurePassword'

# Start aevra with dashboard in browser
aevra start --ui

macOS & Linux (zsh / bash)

# 1. Install aevra globally
npm install -g @the-long-ride/aevra@latest

# 2. Configure admin credentials and launch daemon with Web UI
export AEVRA_USERNAME="admin"
export AEVRA_PASSWORD="YourSecurePassword"
aevra start --ui

(Optional) Run aevra automatically as a user-level background service:

aevra service install
aevra service start

---

Quick Connect Guide

aevra exposes a standard MCP endpoint (/mcp) that can be accessed either directly over HTTPS (e.g. https://localhost:47830/mcp or direct IP/domain) or exposed to the internet through a tunnel (Cloudflare Tunnel, ngrok, Tailscale Funnel, Caddy, FRP, reverse SSH).

1. Connect ChatGPT (Custom Plugin / Action)

1. In ChatGPT, create a new Custom Plugin / Action:
   • Name: aevra (or any custom name)
   • Server URL: https://<your-aevra-host>/mcp (e.g. your tunnel or public URL)
   • Authentication: OAuth
2. ChatGPT initiates the OAuth 2.0 PKCE discovery flow; open your local aevra Web UI (https://localhost:47831) and click Allow on the pairing request.
3. Under ChatGPT plugin / action settings, grant Permission for Plugins -> Allow all actions so commands and tool calls execute through aevra without recurring client confirmation dialogs.

2. Connect Claude, Grok, etc. & Other MCP Clients (Custom Connector)

Claude example:

1. Open Claude and navigate to Customize or your account Settings, then select Connectors.
   • Name: aevra (or any custom name)
   • Server URL: https://<your-aevra-host>/mcp (e.g. your tunnel or public URL)
   • Authentication: OAuth
2. Other steps are familiar with ChatGPT.

OAuth connection continuity

Aevra cannot guarantee one physical HTTP/MCP transport remains open. Continuity is achieved by re-authenticating with a short-lived access token or rotating a refresh token and reattaching to the same logical connection.

By default, access tokens last 60 minutes, the refresh family has an absolute 30-day lifetime, and an interrupted MCP session gets a 15-minute reconnect grace window. The durable connection can preserve remembered workspace grants and connection-level YOLO, but session-only leases still expire independently.

Aevra does not automatically replay a lost mutating request after reconnect. Use operation_get or operation_list to inspect a connection-owned durable operation result before deciding whether another write, commit, delete, or command is necessary.

---

Tips

Security

• Rotate credentials regularly: Update AEVRA_USERNAME / AEVRA_PASSWORD via [System.Environment]::SetEnvironmentVariable (Windows) or update the export in your shell profile (macOS / Linux) and restart aevra.
• Scope tunnel exposure: Publish the MCP/OAuth publicUrl for AI clients. Keep the Admin UI local unless you intentionally configure a separate HTTPS adminPublicUrl and explicit trusted Admin origins; the MCP public origin is not trusted for Admin mutations automatically.
• Use capability profiles: Assign the least-privilege profile per connector in the Web UI. Prefer Read-Only or Safe Dev for AI web clients and reserve Full Access for trusted local sessions.
• Audit regularly: Review the tamper-evident audit log in the Web UI (Activity tab) to spot unexpected tool calls or policy overrides.

Performance

• Scope workspace search: Use search with explicit include / exclude glob patterns. Unbounded searches on large monorepos will be slower — pin to the relevant subdirectory.
• Parallel managed processes: Prefer process_start + process_wait for long-running builds or test suites instead of blocking terminal commands. aevra tracks them across reconnects.
• Change set rollbacks: Use journaled change sets for multi-file edits. If a mid-task error occurs, a single rollback call restores all files atomically without manual undo.
• Keep aevra as a background service: Run aevra service install && aevra service start so the gateway survives reboots and reconnects from AI clients automatically.

Remote Working through AI Chat Web Interfaces

• Generate images remotely: Ask ChatGPT or Claude to call the file_write tool to save AI-generated image data directly into your local project folder or stage assets for a pipeline.
• Automate research and reporting: Instruct the AI to run search across your notes or data directories, synthesize findings, and write a structured report to a local file — a full research loop without leaving chat.
• Manage social media and content pipelines: Connect aevra to MCP servers that wrap social media APIs or content schedulers. The AI can draft posts, read engagement metrics via command_run, and write scheduled content files — all orchestrated from a single chat session.
• Run multi-step automation as agents: Chain search, command_run, file_write, and git_commit in one prompt. The AI acts as an autonomous agent that finds, processes, writes, and records results end-to-end with no manual handoffs.
• Collaborate on code: Point ChatGPT or Claude at your local repository through aevra. The AI can read files, run tests via command_run, apply edits, and commit — all in one conversation thread.
• Office coworking: Use aevra to let AI clients read, draft, and write local documents (.md, .docx via scripts, .csv). Automate repetitive tasks such as report generation, data summarization, or template filling directly from chat.
• Multi-client workflows: Connect multiple AI chat web interfaces simultaneously — for example ChatGPT for drafting and Claude for review. Each connector gets its own capability profile so you control exactly what each client can touch.
• Untethered mobile development: Pair a remote aevra instance with ChatGPT or Claude mobile apps. Prompt the assistant to fix bugs, run test suites, or generate files on your remote workspace from anywhere without sitting at a desk.

Fully Remote Setup (Server / Headless Device & Remote Web UI)

• Deploy on an always-on device or server: Install and run aevra as a background service (aevra service install && aevra service start) on a dedicated Linux VPS, home lab, Mac mini, or NAS. Your workspaces, tools, and background processes remain online 24/7 without needing your personal laptop powered on or connected.
• Access Admin Web UI anywhere: Reach the aevra Admin Dashboard remotely over a secure private network (such as Tailscale, WireGuard, or an authenticated reverse proxy like Caddy / Cloudflare Access). Monitor real-time MCP activity, inspect sanitized payloads, and adjust workspace grants from any mobile device, tablet, or browser.
• Step-up approvals on the go: When an AI client triggers sensitive operations that require confirmation (policy.critical.alwaysConfirm), approve or reject them directly from your phone in the remote Web UI.
• True fully remote AI autonomy: With MCP exposed over HTTPS / tunnel and the Web UI reachable remotely, you achieve complete untethered control. Trigger long-running jobs (process_start), git workflows, and multi-file code modifications from ChatGPT, Claude, or Grok while supervising everything remotely.
• Split-plane network isolation: Keep MCP/OAuth and Admin exposure independent: publish the MCP publicUrl for AI clients, and expose adminPublicUrl only when needed through a private VPN or explicitly trusted HTTPS origin.

Hooks

• Pre- and post-tool hooks: Define hooks.pre and hooks.post entries in your workspace aevra.config.json to run scripts automatically before or after specific MCP tool calls — useful for linting before a commit, sending a notification after a file write, or triggering a build on code change.
• Abort dangerous operations: A pre hook that exits non-zero cancels the tool call entirely. Use this to block destructive commands (rm -rf, DROP TABLE) in specific directories or enforce custom policy rules beyond aevra's built-in capability profiles.
• Chain external services: Use post hooks to forward tool results to external services — post a Slack message when a report is generated, sync files to cloud storage after a write, or trigger a CI pipeline after a git commit.
• Per-workspace hook isolation: Hooks are scoped to the workspace config file, so different projects can have different automation rules without affecting one another.

---

Documentation & Guidelines

• Installation & Development Guideline: Building from source, development scripts, test suites, architecture boundaries, and troubleshooting.
• Technical Specifications: In-depth design documents for engineers and AI coding agents.
• User Manual: 2-minute modular guides for tunnels, connectors, workspaces, permissions, and service setups.
• Changelog: Release history and version notes.

---

Companion

AI Chatweb Supporter is a companion Chromium extension that enhances ChatGPT, Claude, and Grok directly in the browser — improving usability and productivity when working alongside aevra.

---

License

MIT (c) aevra Contributors