Relay Shell

v0.5.0 · Python 3.12 / 3.14 · transports stdio and streamable-http · MCP SDK mcp>=2,<3 · Apache-2.0

relay-shell is a Model Context Protocol server that gives an MCP client the full reach of a shell: run commands on the local host, hold interactive PTY sessions, run scripts, operate a fleet over SSH, move files with SFTP and open port forwards.

It is operator infrastructure for hosts you own and administer. It runs with the privileges of its service account, with no sandbox, and it is open by default: no command is refused for what it does. What it adds is a record and a warning:

• Every call is audited: one JSON line with the redacted arguments, the output's hash and length (never its body), the exit code, the client and the assessed tier.
• Every risky call says so: a call classified Tier 2 (changes state) or Tier 3 (irreversible), or an SSH call with host-key checking off, ends with a [NOTICE ...] line. server_info lists the standing unsafe settings.
• Refusal is opt-in: guarded and readonly modes, a deny list and a Tier-3 confirmation step are available and all off by default.

Tools

The server also exposes three read-only MCP resources (relay-shell://inventory, relay-shell://inventory/{host}, relay-shell://ssh-config) and one prompt, operating_guide, with guidance on which tool to use when; resource reads and prompt fetches are audited too. Full reference: docs/tools.md. Over HTTP, GET /metrics serves Prometheus counters and gauges (docs/deployment.md §9a).

Quickstart

Qualified host profiles are Ubuntu 24.04 LTS with CPython 3.12 and Ubuntu 26.04 LTS with CPython 3.14. Use the matching hashed dependency profile. The package minimum is CPython 3.12; other interpreter/OS combinations are not qualified.

git clone https://github.com/rmednitzer/relay-shell.git && cd relay-shell
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

relay-shell                              # stdio transport
RELAY_SHELL_TRANSPORT=http relay-shell   # streamable-http on 127.0.0.1:8080
relay-shell --check-config               # validate config, print unsafe-setting notes
relay-shell --verify-deploy              # compare installed templates with the shipped ones

Register with an MCP client (stdio):

{ "mcpServers": { "relay-shell": { "command": "relay-shell" } } }

Configuration comes from RELAY_SHELL_* environment variables, optionally via a .env file; see .env.example and docs/deployment.md.

Default behaviour

With the default configuration every command on every tool is admitted, including rm -rf /, mkfs, dd to a block device, shutdown, curl | sh and sudo (pinned by tests/test_notices.py). The call is classified and audited, and a risky one ends with a notice:

[exit 0]
...command output...
[NOTICE tier 3 (IRREVERSIBLE), matched an irreversible-operation pattern. It may not be
undoable and ran with no confirmation step; verify the target and take a backup or snapshot
first. Classification is a heuristic, not a boundary]

The classifier is a regex heuristic over the command text, not a parse of the shell language. A call without a notice is not thereby safe, and a notice does not block anything.

Only resource bounds and one startup check refuse a call, none of them based on what the command does:

Session output buffers are also bounded, and idle sessions (RELAY_SHELL_SESSION_IDLE_TIMEOUT, 1800 s) and exited, drained sessions are reaped.

Making it stricter

Every option below is opt-in and they combine:

Security

The server grants real administrative power. Run it as a scoped service account, only on hosts you are authorized to administer, behind the network controls in docs/deployment.md. A privileged (root or sudo) deployment is supported for isolated administrative hosts with strict network controls and full audit shipping. SECURITY.md has the threat model and how to report a vulnerability.

Besides the audit record, notices and bounds above:

• Audit integrity: the log is append-only on disk with a rotation-safe handler. The optional hash chain makes edits, insertions, reorders and interior deletions detectable with relay-shell --verify-audit (fail-closed); detecting tail truncation needs the off-host copy.
• Redaction: audited arguments are scrubbed of tokens, keys and Authorization material. Heuristic; tested with synthetic secrets.
• Syscall visibility (optional): RELAY_SHELL_SECCOMP_NOTIFY records a spawned child's execve, privilege, namespace, mount, write-open and privilege-relevant prctl syscalls. It never blocks a syscall and installs only with CAP_SYS_ADMIN.
• OAuth 2.1 (optional, off by default): dynamic client registration behind an operator approval gate, PKCE, rotating refresh tokens with reuse detection. See docs/auth.md.
• Edge: the Caddy config from deploy/install-edge.sh restricts the MCP endpoint to known CIDRs, adds security headers, caps public OAuth request bodies, keeps authorization codes out of the access log and automates TLS via ACME. The systemd unit applies resource caps.

Compatibility

Development

ruff check . && ruff format --check .
mypy
pytest

Layout: src/relay_shell/ (server and modules), deploy/ (systemd unit, Caddyfile, logrotate, installers, off-host audit sync, monitoring), docs/ (start at docs/index.md), tests/ (unit and integration; an in-process SSH server, no network).

CONTRIBUTING.md covers scope, branch naming, the local loop and review of security-sensitive changes; docs/runbook.md holds the audit, review and validation procedures and the backlog. AI agents follow AGENTS.md (with CLAUDE.md for Claude). Participation is governed by the Code of Conduct.

License

Apache-2.0. See LICENSE and NOTICE.