Relay Shell

v0.5.2 · 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:

• Per-call audit: 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.

• Risk notices: 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.

Audit records describe completed, denied and cancelled calls; a process crash can leave an execution without a completion record. Opt-in RELAY_SHELL_AUDIT_INTENT=true adds a pre-execution record. Runtime sink failures mark audit health degraded while calls continue; monitor that health and ship evidence off-host. See the audit lifecycle.

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).

Related MCP server: SSH MCP Server

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.12 -m venv .venv
. .venv/bin/activate
python -m pip install --only-binary=:all: --require-hashes -r requirements/development-py3.12.txt
python -m pip install --no-deps --no-build-isolation -e ".[dev]"
python -m pip check

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

The example uses Ubuntu 24.04 / CPython 3.12. On Ubuntu 26.04, use python3.14 and requirements/development-py3.14.txt instead. For a service installation using the runtime-only lock and an isolated builder, follow the deployment guide.

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.

Open mode controls command admission; it does not bypass argument validation, SSH host verification, transport authentication or resource limits. With the default policy, a command is not refused because of its meaning. Important bounds and startup checks include:

Session output buffers are also bounded, and idle sessions (RELAY_SHELL_SESSION_IDLE_TIMEOUT, 1800 s) and exited, drained sessions are reaped. Persistent sessions have no maximum lifetime. SFTP transfers default to timeout=0 (no per-call deadline); set a positive transfer timeout when needed. After a remote timeout or disconnect, reconcile the remote operation before retrying a mutation.

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.