aev-web

aev-web is the Aev web terminal plugin crate from Trevor Knott / Knott Dynamics. It provides a local, token-protected HTTP server for controlling PTY-backed terminal sessions from a browser or another local tool.

It also exports the future Aev plugin entrypoint aev_plugin_init and advertises the aev.plugin.v1 manifest contract.

Package

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

What It Does

• Starts a local HTTP server, default 127.0.0.1:8765.
• Generates a bearer token unless AEV_WEB_TOKEN is provided.
• Serves a small browser UI at /.
• Creates PTY-backed shell sessions with UUIDv7 IDs.
• Lets clients write terminal input and poll terminal output.
• Keeps output in a bounded in-memory ring buffer.
• Exposes an Aev plugin manifest at /api/manifest.

Install

From crates.io:

cargo install aev-web

From source:

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

Quick Start

Run with a generated token:

aev-web

Run with a stable token:

AEV_WEB_TOKEN=replace-with-a-secret aev-web --bind 127.0.0.1:8765

The server prints a local URL like:

open http://127.0.0.1:8765/?token=<token>

Open that URL in a browser on the same machine.

Configuration

Keep the default loopback bind unless you intentionally expose terminal access through a separate bridge such as aev-bridge.

HTTP API

Public health endpoint:

curl http://127.0.0.1:8765/health

Authenticated requests use Authorization: Bearer <token>.

Create a session:

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

Create a custom command session:

curl -sS -X POST http://127.0.0.1:8765/api/sessions \
  -H "Authorization: Bearer $AEV_WEB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"/bin/sh","args":["-lc","pwd && whoami"],"rows":24,"cols":100}'

Write terminal input:

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

Read terminal output:

curl -sS "http://127.0.0.1:8765/api/sessions/$SESSION_ID/output?since=0" \
  -H "Authorization: Bearer $AEV_WEB_TOKEN"

Terminate a session:

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

API Routes

• GET /health returns public server health.
• GET /api/manifest returns the aev-web plugin manifest.
• POST /api/sessions creates a PTY-backed terminal session.
• GET /api/sessions lists active sessions.
• GET /api/sessions/{id} returns one session summary.
• GET /api/sessions/{id}/output?since={cursor} reads terminal output.
• POST /api/sessions/{id}/input writes terminal input.
• DELETE /api/sessions/{id} terminates a 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-web git https://github.com/Tknott95/AevWeb.git aev_plugin_init tool,terminal,web,local-http,bearer-auth
/plugins validate all

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

Use With aev-bridge

Use aev-web as the local terminal owner and aev-bridge as the phone/LAN bridge:

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

Then start aev-bridge with the same upstream token:

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

Security

• Treat AEV_WEB_TOKEN as terminal access.
• Keep aev-web bound to loopback unless you know exactly why it must be reachable elsewhere.
• Prefer aev-bridge for phone access instead of exposing aev-web directly.
• The browser UI stores the token in local storage for convenience.
• Do not put real tokens in committed .env files.

Development

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

Release Notes

See CHANGELOG.md.