aev-bridge

aev-bridge is the Aev bridge plugin crate from Trevor Knott / Knott Dynamics. It exposes a phone-friendly HTTP and Server-Sent Events interface that proxies to aev-web.

aev-bridge intentionally does not own PTYs or spawn terminal processes. aev-web owns terminal sessions, and aev-bridge focuses on safe LAN/mobile access and streaming output to browser clients.

Package

• Crate: aev-bridge
• Binary: aev-bridge
• Plugin ID: aev-bridge
• Plugin entrypoint: aev_plugin_init
• Protocol: aev.plugin.v1
• Author: Trevor Knott
• Organization: Knott Dynamics
• Repository: https://github.com/Tknott95/AevBridge

What It Does

• Binds a phone-accessible bridge server, default 0.0.0.0:8780.
• Requires a bridge token for browser/API access.
• Proxies session creation, input, listing, and termination to aev-web.
• Streams terminal output over Server-Sent Events at /api/sessions/{id}/events.
• Accepts query-token auth for SSE because browser EventSource cannot set authorization headers.
• Prints a LAN URL when it can detect one.
• Exposes an Aev plugin manifest at /api/manifest.

Install

From crates.io:

cargo install aev-bridge

From source:

git clone https://github.com/Tknott95/AevBridge.git
cd AevBridge
cargo run

Quick Start

Start aev-web first:

AEV_WEB_TOKEN=replace-with-a-secret aev-web

Start the bridge with the same upstream token and a phone token:

AEV_WEB_TOKEN=replace-with-a-secret AEV_BRIDGE_TOKEN=phone-secret aev-bridge

The bridge prints a URL like:

phone URL: http://192.168.1.50:8780/?token=phone-secret

Open that URL from a phone on the same LAN.

Configuration

Use --bind 127.0.0.1:8780 if you only need local browser access and do not want LAN exposure.

HTTP API

Public health endpoint:

curl http://127.0.0.1:8780/health

Authenticated fetch requests use Authorization: Bearer <bridge-token>.

Create a terminal session through the bridge:

curl -sS -X POST http://127.0.0.1:8780/api/sessions \
  -H "Authorization: Bearer $AEV_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Write terminal input:

curl -sS -X POST http://127.0.0.1:8780/api/sessions/$SESSION_ID/input \
  -H "Authorization: Bearer $AEV_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":"pwd\r"}'

Stream terminal output from JavaScript:

const events = new EventSource(`/api/sessions/${sessionId}/events?token=${bridgeToken}`)
events.addEventListener("output", (event) => {
  const output = JSON.parse(event.data)
  console.log(output.data)
})

Terminate a session:

curl -sS -X DELETE http://127.0.0.1:8780/api/sessions/$SESSION_ID \
  -H "Authorization: Bearer $AEV_BRIDGE_TOKEN"

API Routes

• GET /health returns public bridge health.
• GET /api/manifest returns the aev-bridge plugin manifest.
• GET /api/upstream/health checks the configured aev-web upstream.
• GET /api/sessions proxies active session listing.
• POST /api/sessions proxies session creation.
• GET /api/sessions/{id} proxies one session summary.
• GET /api/sessions/{id}/events streams output as SSE.
• POST /api/sessions/{id}/input proxies terminal input.
• DELETE /api/sessions/{id} terminates the upstream session.

Aev Registration

The current Aev plugin board validates descriptors and contracts. It does not load plugin code yet. Register the descriptor with:

/plugins add aev-bridge git https://github.com/Tknott95/AevBridge.git aev_plugin_init tool,bridge,mobile,http,sse,bearer-auth
/plugins validate all

See examples/plugins.json for an equivalent .aev/plugins.json entry.

Security

• Treat AEV_BRIDGE_TOKEN as phone/browser access to your bridge.
• Treat AEV_WEB_TOKEN as upstream terminal access.
• Keep both tokens out of committed files.
• LAN binding means other devices on the network can attempt to connect.
• Use a strong bridge token when binding to 0.0.0.0.
• Prefer trusted local networks; this is not an internet-exposed gateway.

Development

cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
cargo publish --dry-run

Release Notes

See CHANGELOG.md.