clum MCP server
Commit Oct 25, 2026Provides secure, persistent terminal sessions and multi-host orchestration for AI agents and human operators on Linux hosts.
Also known as tddh/clum
- Stars
- 6
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 25, 2026
- License
- MIT
What is clum MCP?
clum provides secure, persistent terminal sessions and multi-host orchestration for AI agents and human operators on Linux hosts.
Summary generated from the project's README
About clum MCP server
Managing Linux hosts through autonomous AI agents and human operators is what clum enables by providing secure, persistent terminal sessions. It functions as a remote operations platform that turns terminal sessions into programmable resources. The system uses a central MCP server to communicate with AI clients via HTTP and with human operators through a CLI that features PTY passthrough. To connect to target Linux machines, you deploy an rmux-bridge on each host which reverse-connects to the central server using QUIC.
This setup differs from standard SSH tools by offering built-in reliability, auditability, and security. It uses a Bridge proxy and token authentication to ensure the client never holds server credentials. The platform includes a management layer for multi-host orchestration using tags and groups, and a compliance layer that maintains a structured SQLite audit trail. Developers can use specific tools like batch_exec for multi-host commands, file transfer for recursive directory uploads, and port forwarding to access remote services. The system also features terminal state awareness to prevent AI agents from executing commands while an editor or password prompt is active.
What you can do with it
- 1Compliance and operational auditingEvery action taken by either a human or an AI is recorded in a queryable audit trail for traceability.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
BRIDGE_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletddh/clum is public and reachablegithub.com/tddh/clum ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-25github.com/tddh/clum ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubclum
clum — safe, reliable remote terminals for AI agents. (Renamed from yunying in 0.10.0; lineage: agent-ops → yunying → clum.)
Secure infrastructure for AI agents and human operators managing Linux hosts — persistent terminal sessions powered by rmux, full-chain audit logging, MCP-native interface for AI clients + CLI PTY passthrough for humans, with file transfer, port forwarding, and multi-host orchestration.
Why clum?
AI agents have evolved from "generating commands for humans" to autonomously operating terminals — deploying services, diagnosing failures, running long builds and training jobs, all without human intervention. But traditional terminal tools (SSH, tmux) were designed for human interaction, not programmatic API calls. clum is built on rmux, turning terminal sessions from a human interface into a programmable resource for both AI agents (via MCP) and human operators (via CLI PTY passthrough), with three production-grade layers on top.
Three problems stand between agent prototypes and production deployment, and existing tools (plain SSH MCP servers, basic tmux wrappers) largely ignore them:
- Reliability: Plain SSH drops running processes on disconnect — long-running tasks fail mid-flight. Traditional tmux automation relies on
send-keys + sleep + grep, where any timing drift breaks the workflow. - Auditability: When AI operates servers in production, you must trace who did what, when, on which machine, and with what result. Most SSH tools lack built-in audit capabilities entirely.
- Security boundary: Handing SSH keys directly to an AI client is a massive attack surface. clum uses Bridge proxy + Token auth + TLS encryption to confine server access to the target host — the client side (both MCP and CLI) never holds server credentials.
The three layers: Protocol layer (MCP standard interface for AI clients + CLI PTY passthrough for human operators), Management layer (multi-host registry, group/tag filtering, broadcast operations), and Compliance layer (structured SQLite audit trail covering both MCP and CLI operations, ready for operational traceability). Together they fill the infrastructure gap between agent prototypes and production readiness.
Where does it fit?
clum provides secure, reliable, auditable remote access to Linux hosts — terminal sessions, file transfer, port forwarding, and operation audit. It's not a replacement for SSH (transport layer), Ansible (configuration management), or tmux (terminal multiplexer). It's a new category: a remote operations platform that turns terminal sessions into programmable resources for both AI agents and humans.
clum doesn't care what runs inside the terminal — raw shell commands, Ansible playbooks, build scripts, or interactive debugging. It provides the persistent session + audit trail + multi-host operations, and you bring the tools.
A few patterns:
# Pattern 1: AI reads system state, makes decisions, executes fixes
AI Agent (via MCP)
→ exec: cat /proc/loadavg && df -h # read state
→ AI reasons: "disk full on /var/log"
→ exec: du -sh /var/log/* | sort -rh | head # diagnose
→ exec: journalctl --vacuum-size=500M # fix
→ audit trail: every step recorded in SQLite
# Pattern 2: Human investigates via CLI while AI assists
Human (via CLI PTY passthrough)
→ clum-cli term tf01 # same session AI was working in
→ vim /etc/nginx/nginx.conf # human edits in familiar tools
AI Agent (via MCP)
→ exec: nginx -t && systemctl reload nginx # AI validates & applies
# Pattern 3: Multi-host batch operations
AI (via MCP)
→ host_filter tags=["web"] # select target hosts
→ batch_exec: systemctl status nginx # check all web servers
→ batch_upload: nginx.conf → /etc/nginx/ # push config to all
→ batch_exec: nginx -s reload # reload all at once
Use cases:
- Incident response: AI or human jumps into a live session, reads system state, diagnoses root cause, and executes repairs — all within the same persistent terminal
- Ad-hoc operations: Quick one-off commands across multiple hosts (
batch_exec), file transfers, port forwarding — no Playbook needed - Interactive debugging: Persistent sessions for builds, long-running task monitoring, or interactive troubleshooting via both MCP (AI) and CLI PTY passthrough (human)
- Remote development:
clum-cli term devbox— work on a remote machine with your familiar terminal environment, with AI assistance one keystroke away (Ctrl+G) - Compliance auditing: Full-chain audit trail covering both AI and human operations on every host, queryable via
clum-mcp audit query
Architecture
graph LR
A[AI Client<br/>opencode/Claude/Cursor] <-->|HTTP :9788<br/>MCP Streamable HTTP| S[Central MCP Server<br/>clum-mcp --mode http]
H[Human] <-->|QUIC :9788<br/>PTY / upload / forward| S
S <-->|QUIC :9788<br/>reverse registration| C1[rmux-bridge<br/>host-1]
S <-->|QUIC :9788| C2[rmux-bridge<br/>host-2]
S <-->|QUIC :9788| C3[rmux-bridge<br/>host-N]
C1 <-->|Unix Socket| D1[RMUX daemon]
C2 <-->|Unix Socket| D2[RMUX daemon]
C3 <-->|Unix Socket| D3[RMUX daemon]
- clum-mcp (Central Server) — Central MCP Server: HTTP :9788 for AI clients (MCP protocol) + QUIC :9788 for Bridge registration and CLI data plane. Provides 68 tools, centralized audit, API Key auth, and static file serving.
- clum-cli — CLI for humans: PTY passthrough (
term), file transfer (push/pull— files or directories, chunked streaming with SHA-256;pushsupports--excludeglobs for directories), port forwarding (forward— auto-reconnects on network loss,--give-up-after), session listing (list), recording playback (replay). Built-in AI chat panel (Ctrl+G). Congestion control defaultauto: BBR on private targets, CUBIC on public targets (loss-adaptive, avoids disconnects at full bandwidth); override with--cc bbr|cubic|auto(orCLUM_CCenv var). - rmux-bridge — Agent deployed on each Linux host. Reverse-connects to the Central Server, handles tool execution, file I/O, PTY sessions, and recording push.
- RMUX daemon — Terminal multiplexer on each Linux host (rmux-based).
Deployment model:
| Component | Runs on | Connects to |
|---|---|---|
clum-mcp --mode http |
Central server (1 instance) | — |
rmux-bridge |
Each target Linux host | Central Server (QUIC, reverse registration) |
| AI clients | Any machine | Central Server (HTTP, MCP protocol) |
clum-cli |
Operator machine | Central Server (QUIC, --server-addr) |
💡 New bridges deploy with one command (after the server's
releases/assets are staged — see below):curl -fsSLk -H "Authorization: Bearer <download_token>" https://SERVER:9788/releases/install.sh | BRIDGE_TOKEN=xxx SERVER_ADDR=SERVER:9788 sh
<download_token>andBRIDGE_TOKEN=xxxare the same bridge token (fromclum-mcp bridge add) — the install script uses it both for the download header and for registration.⚠️
/releases/*is served from<static_dir>/releases/, and no deployment script stages those files. Putdeploy/install.sh,certs/ca.crtand the bridge binary (namedrmux-bridge-linux-<arch>) under<static_dir>/releases/first — otherwise the URL returns nothing.
💡 During deployment, the bridge auto-detects the RMUX socket path — no manual configuration needed.
Features
| Feature | Description |
|---|---|
| Interactive terminal | clum-cli term — transparent raw pane passthrough by default (no rmux UI layer, ssh-like); --mux opts into the full rmux attach-session UI (status bar + Ctrl+B prefix). Auto-creates the session if it doesn't exist. Built-in AI chat panel (Ctrl+G) with real-time SSE streaming; supports vim/htop/TUI |
| Session management | Create/destroy/list sessions, multi-pane splits, window layouts |
| Command execution | exec one-shot execution (sentinel detection + exit code, full scrollback capture for large outputs, auto-reconnect on connection drop), interactive programs via send_keys + capture_pane |
| Output waiting | wait_for_text for terminal text, wait_exit for process exit, wait_stable for output quiescence, wait_for_bytes for raw byte sequences |
| File transfer | Upload/download over QUIC (clum-cli and MCP tools), recursive directory transfer with concurrency and --exclude globs, chunked streaming with SHA-256 verification |
| Port forwarding | Local port forwarding forwards through QUIC to access remote internal services |
| Multi-host orchestration | Host registry with group/tag/label filtering, broadcast_keys for multi-pane |
| Audit logging | SQLite audit logs + bridge-side PTY recording (asciinema v2 content, encrypted at rest via X25519 + AES-256-GCM) + event log + push/periodic sync + clum-cli replay playback |
| Terminal state awareness | capture_pane, exec, wait_for_text, wait_stable, pane_info return terminal_state (ready/running/editor/pager/password/confirm/repl/unknown) and cursor position, so AI agents know what the terminal is currently doing |
| Exec safety check | exec refuses execution when terminal is not in ready state (e.g., inside vim, less, password prompt), returning refused: true with actionable guidance to prevent command injection; state-detection failures also refuse (fail-closed) |
| Command rule engine | permissive (default) / strict policy before execution (clum-command-kb). Quote-aware normalization splits &&/;/|/redirects/command-substitution and strips sudo/env/timeout wrappers; compound commands take the strictest verdict. In permissive mode anything not matching an explicit deny runs; the destructive list lives in config/command-rules.toml (rm critical paths, dd block devices, mkfs/partitioning, shutdown, firewall flush, kill init, interpreter/xargs wrappers). No human approval channel. Policy keys on tool × program × argv regex × host group × caller group. The 1,607-entry knowledge base is retained as legacy reference (it no longer affects permissive verdicts); its read_only marks still serve command:read |
AI Chat Panel Keybindings
Inside the AI panel (activated via Ctrl+G):
| Key | Action |
|---|---|
Ctrl+G / Esc |
Close AI panel, return to terminal |
Ctrl+C |
Stop current AI generation (stay in panel) |
Enter |
Send message |
Backspace |
Delete last character |
↑ / PageUp |
Scroll message history up (older messages, exits follow mode) |
↓ / PageDown |
Scroll message history down (scrolling to the bottom resumes follow mode) |
Mouse Scroll |
Scroll message history |
The message view auto-scrolls to the latest output (follow mode) while the AI streams; scrolling up pauses it for reviewing history, and scrolling back to the bottom resumes it. While waiting for a response, an animated spinner with elapsed seconds is shown.
| Command | Action |
|---|---|
@analyze |
Analyze current terminal content |
@clear |
Clear conversation history |
The AI panel starts an opencode serve process on first use (port 14096). It persists across panel open/close cycles and is cleaned up when the CLI exits. Use --opencode-dir <path> to control the working directory (default: current directory).
PTY passthrough mode forwards raw terminal bytes — mouse events work when the remote application enables mouse mode (e.g., vim, htop).
Quick Start
Build
# Native build (macOS dev)
cargo build -p clum-mcp --release
cargo build -p clum-cli --release
# Cross-compile bridge + MCP server for Linux x86_64 (static)
just release-linux
Deploy
# Step 1: Deploy rmux daemon (on remote host)
bash deploy/install-daemon.sh root@<your-bridge-ip>
# Step 2: Compile & deploy bridge (one-shot)
just release-linux
BRIDGE_TOKEN="<your-token>" CLUM_SERVER_ADDR=SERVER:9788 just deploy-bridge host=root@<your-bridge-ip>
Host Registry
Create config/hosts.yaml (see config/hosts.example.yaml):
hosts:
# Enrolled mode (recommended) — bridge reverse-registers, no addr/token needed:
- name: prod-web-01
group: production
tags: [web, nginx]
labels:
dc: shanghai
# Direct mode (fallback) — connect to bridge directly:
- name: legacy-host
bridge_addr: 10.0.1.10:9778
bridge_token: "your-token-here"
💡 Hot-reload: After editing
hosts.yaml, reload without restarting — either call thereload_configMCP tool or sendkill -HUP <pid>to the MCP server process.
MCP Client Config
Central Server mode (recommended — one URL + API Key):
{
"mcp": {
"clum": {
"type": "remote",
"url": "https://SERVER:9788/mcp",
"headers": { "Authorization": "Bearer yk_name_..." }
}
}
}
Local stdio mode (no central server, direct connections):
{
"mcp": {
"clum": {
"type": "local",
"command": ["/path/to/clum-mcp"],
"args": ["--ca-cert", "/path/to/ca.crt", "--hosts-file", "/path/to/hosts.yaml"],
"enabled": true
}
}
}
Use
ca.crtfor remote deployments;bridge.crtworks for local self-signed testing.
Server Management
# API Key management
clum-mcp agent add <name> (--group <g> | --admin) # Create key (--admin = superadmin, --group = restricted)
clum-mcp agent list # List all keys (shows GROUP column)
clum-mcp agent rotate <name> # Rotate a key (inherits group)
clum-mcp agent revoke <name> # Revoke a key
# Group isolation: grouped keys can only access hosts in their group.
# host_list/audit_query/recordings auto-filter; reload_config/host_set_meta blocked.
# Role / capability policy (P0): default deny; existing keys migrate to legacy roles
clum-mcp role list
clum-mcp role grant operator --group dev --actions host:read,session:attach,command:exec
# --require-approval only tightens allow -> ask. Under the default `permissive`
# policy ask still executes; it blocks only under `command_policy: strict`.
# There is no human approval channel.
clum-mcp role grant operator --group prod --actions command:exec
clum-mcp role bind --key agent-dev --role operator
clum-mcp policy explain --key agent-dev --tool exec --host tf001
# Bridge enrollment (dynamic registration, no hosts.yaml edit needed)
clum-mcp bridge add <hostname> --tags <t1,t2> [--group <g>]
clum-mcp bridge list
clum-mcp bridge remove <hostname>
clum-mcp bridge join <hostname> # Generate a new join token (offline recovery)
When no API keys exist yet (fresh install), the server runs in bootstrap mode: loopback connections act as superadmin (console access on the server host); non-loopback requests are rejected until the first
agent addcreates a key.
Security
| Mode | Description |
|---|---|
| CA verified | All server→bridge connections verify the bridge certificate against the CA root (--ca-cert) — full chain + hostname check, no insecure mode. --ca-cert may be omitted in pure enrolled deployments (bridges initiate the connection). In direct mode, omitting it falls back to the system WebPKI roots — which works only for publicly-signed bridge certificates; a private CA must be passed explicitly. |
Production: Run your own CA, issue per-bridge certificates, MCP server holds only the CA root.
Built-in protections:
- Path traversal prevention: File upload/download rejects paths containing
.. - Tunnel target whitelist: Optional
allowed_forward_targetsinhosts.yamlrestricts port forwarding targets (glob patterns) — applies to hosts defined inhosts.yaml; dynamically-enrolled bridges without a matching entry have no whitelist (all targets allowed) - Exec safety check:
execrefuses execution when terminal is not inreadystate (prevents command injection into vim/less/password prompts); detection failures also refuse (fail-closed) - Role/capability layer (P0): each API key is an independent principal, evaluated as
role → grant (resource selector × capability)before the command rule engine. Default deny; existing keys migrate to legacy roles (behaviour unchanged);adminis not intended for the agent runtime; policy lives in the audit DB and everyrolemutation is sealed into the audit hash chain.command:readpermits only commands explicitly marked read-only (whitelist, default deny,sudois not read-only). CLI relays (term/forward/push/pull/list) are checked by purpose at connection establishment — cross-group or ungranted relays are rejected;replayuses HTTPS/recordingsand is checked with the same host +recording:readrule - Command rule engine: every command-carrying tool call (
exec,shell_command,batch_exec,send_keys,send_text,batch_send_keys,broadcast_keys,respawn_pane,split_pane_with,cmd_escape) is normalized and judged server-side — an AI client's own permission config can only be stricter, never looser. In permissive mode anything not matching an explicitdenyruns; in strict modeaskfails closed. A destructive-rule hit returnsCOMMAND_DENIED. Verdicts are deterministic and replayable, and every denial is sealed into the audit hash chain. These rules are a guardrail against mistakes, not a security boundary - Sensitive input redaction: Inputs sent while the terminal is in
passwordstate are auto-redacted in the audit log ([REDACTED:N bytes], server-enforced, no opt-out); thesensitiveflag on input tools forces redaction for tokens/2FA codes
Audit
# Recent operations
clum-mcp audit query --format table
# Commands on specific host
clum-mcp audit query --host tf01 --action exec --since 2026-06-01
# Statistics
clum-mcp audit stats
# Manual cleanup
clum-mcp audit cleanup --older-than 30
# Verify hash-chain integrity (Chain head can be copied to an external
# system for offline comparison — see INVARIANTS.md §8)
clum-mcp audit verify
# Chain check: OK / Hashed events: 12345 / Chain head: <hex64>
Audit data stored at ~/.clum/audit.db, retained 90 days, 500 MB soft cap (cleanup prunes the oldest events; file size may transiently exceed the cap). Every event is sealed into a forward hash chain (entry_hash = SHA256(prev_hash ‖ payload)); audit verify recomputes the full chain and exits non-zero on the first tampered or missing record.
Knowledge Base (Design Concept)
clum produces detailed audit trails for every operation, but raw audit logs answer "what happened" — not "why it happened" or "how to fix it next time." This section outlines a design philosophy for turning operational experience into a shared knowledge base. The implementation is deliberately left to users, because knowledge base backends are a matter of team infrastructure preference, not tooling prescription.
The Problem
After an AI-driven troubleshooting session:
- Knowledge stays local: the diagnosis, root cause, and fix live only in the chat transcript.
- No sharing: other team members can't search for similar past incidents.
- Manual overhead: writing up a postmortem or wiki entry requires remembering context days later.
Three-Layer Design
┌─────────────┐ session activity ┌──────────────────┐
│ clum │ ─── audit events ────→ │ Knowledge │
│ (MCP) │ (SQLite) │ Extraction │
└─────────────┘ │ (AI review) │
└────────┬─────────┘
│ structured entry
▼
┌──────────────────┐
│ Output Adapter │
│ (user-defined) │
└───┬──┬──┬──┬────┘
│ │ │ │
ONES │ wiki GitBook ...
│
curl / git / webhook
1. Collection (built-in)
The existing audit system records every MCP tool invocation and CLI operation — exec, capture_pane, session_create, term, etc. — with timestamps, host, success/failure, and error messages. No changes needed.
2. Extraction (AI-driven)
When the user explicitly triggers "save this session as knowledge," the AI reviews the full conversation history plus the audit trail for that session. It extracts:
| Field | Source |
|---|---|
| Problem | User's initial report, error outputs |
| Diagnosis path | Sequence of exec / capture_pane calls |
| Root cause | Final finding before the fix |
| Solution | The command or configuration change that resolved it |
| Affected hosts / tags | From audit event metadata |
The output is a structured JSON entry, not a Markdown file — so the output adapter can transform it to any format.
3. Output (user-defined)
We intentionally do NOT build platform-specific integrations. Instead, users define a sink — a script, command, or webhook that receives the knowledge entry via stdin (JSON). Examples:
# ~/.clum/sink.sh — push to ONES wiki
curl -X POST "https://ones.example.com/wiki/api" \
-H "Authorization: Bearer $TOKEN" \
-d "$(cat)"
# Push to a git-based knowledge repo
echo "$(cat)" >> knowledge.jsonl && git commit -am "add troubleshooting entry"
Design Principles
- User decides when: knowledge extraction is explicitly triggered, not automatic — avoids noise entries from incomplete sessions.
- User decides where: no platform lock-in. The sink is whatever CLI/API your team already uses.
- User reviews before publishing: AI-generated entries should be reviewed and edited before being pushed to shared storage.
- JSON as interchange: structured data can be transformed to Markdown, API payloads, database rows, etc.
This design keeps clum focused on operations while enabling teams to build their own knowledge pipelines on top of the audit data it already generates.
clum MCP questions
What is clum used for?
clum provides secure, reliable, and auditable remote access to Linux hosts, including terminal sessions, file transfer, port forwarding, and multi-host operations.
How does clum handle security and credentials?
It uses a Bridge proxy, Token authentication, and TLS encryption to ensure the client side never holds server credentials.