UAEG
Provides authenticated agents with native root-level command execution, background jobs, and persistent PTY terminals on a Debian VPS host, allowing them to manage packages, files, services, and system resources.
Enables agents to manage Docker on the host through native shell execution, such as running commands for containers, images, and Docker-based workloads.
Provides remote shell execution, background jobs, and interactive PTY sessions on a Linux VPS, giving agents native control over the host operating system.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
UAEG — Universal Agent Execution Gateway
UAEG is an open-source gateway that lets a compatible cloud-hosted AI agent execute real shell commands, run background jobs, and drive interactive terminals on a remote Linux VPS over MCP (Model Context Protocol) and HTTPS — with no SSH, no tunnels, no local agent runtime, and no external control plane. The agent stays on its hosting platform; UAEG gives it the full native capabilities of the server, up to and including root.
Current release: v1.0.0 (tag v1.0.0). The repository carries its own audit trail
— release decisions, security findings, and test evidence — under report/.
SECURITY WARNING — READ THIS BEFORE INSTALLING
An authenticated agent receives full, unrestricted root access to the VPS. There is no sandbox, no permission gate, and no confirmation step between a tool call and execution.
UAEG is intended for a dedicated, disposable, experimental VPS operated by a single trusted person. Do not install it on a machine that holds anything you care about.
Optional "restricted paths" are advisory rules communicated to the agent — they are not a security boundary. A root shell can bypass them trivially (FR-014).
The dashboard has a native password login (since v0.3.0). Set the password with
sudo uaeg pass; until then it runs in legacy unauthenticated mode and MUST stay on a private bind. A public (0.0.0.0) dashboard bind requires a password AND HTTPS, or the service refuses to start (fail closed).An agent can stop UAEG itself, rewrite firewall rules, or destroy the operating system. A provider console and snapshots are the recovery path (FR-020).
Read docs/SECURITY.md and docs/LIMITATIONS.md before deploying.
Features
Native execution on the real host — not a simulated filesystem or cloud sandbox (FR-007).
Full root control for authenticated agents, by design (FR-010, FR-013).
Remote MCP over Streamable HTTPS with bearer-key authentication; multiple independent keys with immediate revocation — revoking a key also terminates that key's live sessions and background jobs (FR-004, FR-005, FR-011, FR-012).
Background jobs that survive client disconnects and service restarts with honest state reporting across reboots (interrupted, never falsely running) (FR-009).
Interactive persistent terminals (real PTYs) with input, resize, and reconnection (FR-008).
LAN/loopback dashboard for key management, live sessions, audit logs, and server status (FR-015, FR-016); command text and output previews are secret-redacted in the audit trail.
Dashboard authentication (v0.3.0):
uaeg passsets a scrypt-hashed login password; all pages and API routes then require a revocable server-side session (HttpOnly cookie, CSRF token, per-IP lockout). Public exposure over HTTPS with0.0.0.0is supported safely once a password exists.One systemd service, one SQLite database, three runtime dependencies (FR-019). Fail-closed startup: a broken listener, config, certificate or database stops the whole service with a clear error instead of running half-alive.
Guided installer with an integrity-verified one-line option (FR-001, FR-002); since v0.4.0
install.shis the single public entrypoint — the same downloaded file installs UAEG, performs every future safe upgrade (signature-verified release manifest, auto-backup, zero-data-loss verification, automatic rollback), and manages the service (--check,--dry-run,--rollback,--repair,--start/--stop/--restart/--status) under the upgrade contract.
Related MCP server: TerminalMCP
Architecture
One process, two listeners. The MCP listener is public and bearer-authenticated; the
dashboard listener is private by default and password-protected once uaeg pass has been
run.
Hosted AI agent Operator (browser)
(any remote MCP client) (LAN/loopback, or public with a password)
| |
| HTTPS https://HOST:3902/mcp | HTTP(S) http(s)://HOST:3903
| Authorization: Bearer <UAEG_AGENT_KEY> | (login page -> session cookie)
v v
+---------------------------------------------------------------+
| UAEG service (systemd) |
| |
| +--------------------------+ +---------------------------+ |
| | MCP listener (TLS) | | Dashboard listener | |
| | bearer auth per request | | password login + sessions | |
| | stateful MCP sessions | | optional CIDR allowlist | |
| +------------+-------------+ +-------------+-------------+ |
| | | |
| shared runtime: keys, jobs, PTY sessions, audit log |
| SQLite database (/var/lib/uaeg/uaeg.db, WAL mode) |
+------------------------------+--------------------------------+
|
| native root execution
v
Debian VPS host OS
(shell, files, packages, systemd, Docker, networking)Details: docs/ARCHITECTURE.md.
Quickstart
git clone https://github.com/smahud/uaeg.git
cd uaeg
sudo ./install.sh --domain gw.example.com # see docs/INSTALL.md for all options
sudo uaeg generate --name "my-agent" # prints the full secret exactly onceConfigure the hosted agent with:
Server URL:
https://gw.example.com:3902/mcpHeader:
Authorization: Bearer <UAEG_AGENT_KEY>
Verify from the VPS:
sudo uaeg status
sudo uaeg doctorUpgrading is one command with one file you download once: since v0.4.0 the release's
install.sh asset is a unified installer + verified upgrade bootstrap — it embeds the trusted
release keyring, fetches and Ed25519-verifies each release's signed manifest, then runs the
versioned safe-upgrade updater (auto-detect, backup, zero-data-loss verification, automatic
rollback), and also manages the service. Download it one time, then reuse the same local file
for every future release, even ones that change the upgrade implementation itself
(upgrade contract · bootstrap design):
# one-time setup (verify the download, then):
sudo bash install.sh --domain gw.example.com # fresh install
# every future upgrade AND service command: the same file
sudo bash install.sh # verified safe upgrade to the latest release
sudo bash install.sh --check # status + available update
sudo bash install.sh --rollback # restore the latest upgrade backupv1.0.0 note (live audit 2026-11-10, findings F1–F8): security and reliability hardening from the first full live audit of a production deployment: the MCP tool layer is now fail-closed when a key identity cannot be resolved (F1),
uaeg doctor/statusreport the real listener bind instead of the probe address (F2), the installer summary reads back the effective TLS mode on config-preserving upgrades (F3), self-updates started from inside the service re-exec into a transient systemd scope instead of being killed by their ownsystemctl stop(F4), background jobs run in per-job transient scopes and survive service restarts under systemd (F5, AT-11 verified live), plus log hygiene (F6/F7) and a branch-agnostic upgrade-contract harness (F8). Full audit trail:report/UAEG_LIVE_FINDINGS_AND_FIXES.md(and the live evidence pack underreport/evidence/live-audit-2026-11-10/). Releases are signed withuaeg-release-5(keyring rotation 4→5 — theuaeg-release-4private key is no longer available to the publisher; same operator-visible procedure as every prior rotation, seedocs/BOOTSTRAP.md; fresh downloads trust all five keys, historical manifests keep verifying).
v0.4.1 note (production-incident fix + release-key rotation 3→4): the installer now refuses — before touching anything — to
--repairfrom an older source tree over a newer installation (the 2026-11-08dashboard.tlsincident class), verifies the staged schema against the existing configuration pre-mutation, and runs every config-touching step with a sanitized interpreter. Releases are now signed withuaeg-release-4(keyring rotation; bootstraps downloaded during v0.3.4–v0.4.0 will refuse v0.4.1+ with an explicit "signature invalid / key rotation" error — that is the documented fail-closed behavior; re-downloadinstall.shonce (docs/BOOTSTRAP.md)). A bootstrap downloaded fresh (v0.4.1+) trusts all historical keys and needs no refresh.
The first tool an agent should call is server_info, which reports the execution context and
the advisory usage rules. Full walkthrough: docs/USAGE.md.
Requirements
Debian 13 recommended (Debian 12 supported). Python 3.11 or newer; Debian 13 ships 3.13.
Root access to a VPS dedicated to this purpose.
A public domain pointed at the VPS (recommended — enables Let's Encrypt via certbot), or a public IP with an operator-provided trusted certificate.
Inbound TCP on your chosen MCP port (default 3902) reachable through any firewall.
MCP tools
Tool | Purpose |
| Execution context and advisory usage rules; the agent should call this first |
| Run a bash command synchronously, or launch it as a background job |
| Open an interactive PTY session (persistent terminal) |
| Send keystrokes (including control characters) to a PTY session |
| Read new PTY output since a sequence cursor |
| Resize a PTY session's terminal dimensions |
| Terminate a PTY session |
| List live PTY sessions (used for reconnection) |
| Query a background job's state and exit code |
| Read a background job's captured output with offset/limit |
| Wait (bounded) for a background job to finish |
| Cancel a running background job |
| List background jobs |
Parameter-level reference with worked examples: docs/USAGE.md.
CLI overview
Command | Purpose |
| Run the server in the foreground (used by systemd) |
| Write a default config file (advanced/manual setups) |
| Set or change the dashboard login password (interactive, hidden input, stored as a scrypt hash) |
| Create an agent key; the secret is printed exactly once |
| List keys: ID, name, prefix, status, permissions, created, last used |
| Revoke a key (immediate) and terminate its live sessions/jobs; |
| Issue a replacement secret for a key |
| Inspect and control background jobs (cancel = SIGTERM/SIGKILL the process group) |
| Inspect recorded sessions and terminate live ones (SIGHUP/SIGKILL) |
| Service state, health check, port listeners, counts |
| Full diagnostics: config, data, DB (incl. integrity check), service, ports, TLS (incl. SAN), exec user |
| Read and change configuration |
| Print the version |
Platform compatibility
UAEG works with any hosted platform that lets you add an external MCP server over
Streamable HTTP and set a custom Authorization header on its requests. The platform
must be able to reach a URL with an explicit port (https://host:3902/mcp) and trust the
server certificate.
Platforms that cannot add external MCP servers — stdio-only clients, locked integration catalogs, clients that cannot set custom headers — are unsupported, and UAEG does not claim compatibility with them (FR-006).
A platform's built-in terminal or filesystem tools are not redirected to the VPS; they keep running on the platform. The agent must explicitly call UAEG tools for VPS operations.
Documentation
Document | Contents |
Prerequisites, installer flags and examples, verified one-line install, upgrade, uninstall, firewall notes | |
Binding safe-upgrade contract (clauses U-1..U-12): one command, auto-backup, verify, auto-rollback — enforced by the CI upgrade-contract suite (in Bahasa Indonesia) | |
CLI reference, connecting a hosted agent, all 13 MCP tools with worked examples, job lifecycle, PTY cursors, dashboard guide | |
Full config schema, TLS modes, env overrides, path layout, persistence | |
Process model, request flows, execution subsystems, data model, design decisions | |
Threat model, key handling, TLS guidance, hardening, recovery prerequisites | |
Symptom-to-fix tables, | |
Honest list of known limitations and out-of-scope items | |
AT-01..AT-19 acceptance runbook for a real VPS | |
Product requirements (authoritative spec) |
Security and limitations
UAEG is deliberately a power tool with a thin safety story: authenticated agents get root
and soft restrictions are advisory. The dashboard is password-protected once uaeg pass
has been run; without a password it must stay on a private bind (legacy mode). Before
deploying, read docs/SECURITY.md (threat model and hardening) and
docs/LIMITATIONS.md (known limitations, out of scope).
License
MIT — see LICENSE. UAEG v1.0.0: every suite green and production-live-verified — but it still grants full root execution with no sandbox; treat it accordingly.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceTurns any Linux server into an AI-agent-accessible machine over HTTPS, allowing MCP clients like ChatGPT, Claude, and Grok to securely control files, run shell commands, inspect system state, query SQLite, and work with git behind a bearer token.76 npm4MIT
- AlicenseAqualityBmaintenanceEnables an AI agent to take full control of a machine — running shell commands, editing files, managing git, packages and processes, and reaching the network — with batched execution, server-side variables and selectable tool profiles that keep token usage low. It also speaks HTTP so the same agent can operate a remote build box, NAS or VPS.261MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI clients and agents to execute commands in real interactive PTY sessions, manage host filesystem operations, and access 15 MCP tools via Stdio, SSE, or REST with secure API-key authentication.-
- AlicenseNot gradedqualityBmaintenanceEnables managing Linux hosts and local coding agents from an MCP client through shell commands, files, background jobs, system information, instruction and skill discovery, and optional Claude Code, Codex, or Cursor CLI conversations. It provides privileged remote access with token authentication and can run longer work in the background.MIT