exec-vps-mcp: Instructions file for Codex

AGENTS.md — AI deployer and maintainer guide

Read this file and README.md before editing or deploying the repository.

1. Purpose and non-negotiable behavior

This repository intentionally exposes one unrestricted MCP tool:

exec_vps(command: string, timeout?: number) ->
{exit_code, stdout, stderr, timed_out, truncated}

The tool runs the supplied string through the host shell with shell=True, uses /root as its working directory, and is expected to run from a root-owned systemd service. stdout and stderr are independently capped at 1 MiB; truncated is true when either cap is exceeded.

Do not silently replace this with an allowlist, container sandbox, non-root user, SSH wrapper, or command parser. Those may be sensible designs for another project, but they change the behavior this tutorial exists to demonstrate. If the human asks for a safer variant, explain the trade-off and implement it as an explicit change.

The implementation should remain small. Do not add a web UI, database, queue, scheduler, Docker Compose stack, reverse proxy, OAuth server, plugin framework, or deployment abstraction unless the human explicitly asks for it.

---

2. Architecture

Default profile:

MCP client on the user's computer
        ↓ http://127.0.0.1:8798/mcp
local SSH port forward
        ↓ encrypted SSH connection
VPS 127.0.0.1:8798
        ↓ Streamable HTTP
MCPServer running as root
        ↓ subprocess.Popen(..., shell=True, cwd="/root")
VPS root shell

Optional same-host container profile:

Codex / Agent container
        ↓ private Docker bridge only
host bridge gateway:8798
        ↓
root MCPServer service

The second profile requires an explicit private-network firewall boundary. It is not permission to expose TCP 8798 publicly.

The repository also documents two sanitized deployment paths in docs/real-world-example.md:

Cloud path: Telegram / gateway -> Codex -> vps-admin -> private Docker network -> root MCP

Desktop path: Codex Desktop -> cloud-server plugin -> remote MCP entry -> exec_vps