agent-ops

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 and multi-host orchestration.

AI agents have evolved from "generating commands for humans" toautonomously 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 onrmux, 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 onsend-keys + sleep + grep, where any timing drift breaks the workflow.
- Auditability: When AI operates servers in production, you must tracewho 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), andCompliance 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.

clum providessecure, 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: aremote operations platformthat 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 thepersistent session + audit trail + multi-host operations, and you bring the tools.

# 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

- 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 viaclum-mcp audit query

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

💡 New bridges deploy with one command:curl -fsSLk -H "Authorization: Bearer <download_token>" https://SERVER:9788/releases/install.sh | BRIDGE_TOKEN=xxx SERVER_ADDR=SERVER:9788 sh

💡 During deployment, the bridge auto-detects the RMUX socket path — no manual configuration needed.

Inside the AI panel (activated viaCtrl+G):

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.

The AI panel starts anopencode serveprocess 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).

# 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

# 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>" just deploy-bridge host=root@<your-bridge-ip>

Createconfig/hosts.yaml(seeconfig/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 editinghosts.yaml, reload without restarting — either call thereload_configMCP tool or sendkill -HUP <pid>to the MCP server process.

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 } } }

Useca.crtfor remote deployments;bridge.crtworks for local self-signed testing.

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

Production: Run your own CA, issue per-bridge certificates, MCP server holds only the CA root.

- Path traversal prevention: File upload/download rejects paths containing..
- Tunnel target whitelist: Optionalallowed_forward_targetsinhosts.yamlrestricts port forwarding targets (glob patterns)
- Exec safety check:execrefuses execution when terminal is not inreadystate (prevents command injection into vim/less/password prompts)

# 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

Audit data stored at~/.clum/audit.db, retained 90 days, max 500 MB.

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, becauseknowledge base backends are a matter of team infrastructure preference, not tooling prescription.

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.

┌─────────────┐ session activity ┌──────────────────┐ │ clum │ ─── audit events ────→ │ Knowledge │ │ (MCP) │ (SQLite) │ Extraction │ └─────────────┘ │ (AI review) │ └────────┬─────────┘ │ structured entry ▼ ┌──────────────────┐ │ Output Adapter │ │ (user-defined) │ └───┬──┬──┬──┬────┘ │ │ │ │ ONES │ wiki GitBook ... │ curl / git / webhook

The existingaudit systemrecords 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.

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:

The output is astructured JSON entry, not a Markdown file — so the output adapter can transform it to any format.

We intentionally do NOT build platform-specific integrations. Instead, users define asink— a script, command, or webhook that receives the knowledge entry viastdin(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"

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

69 MCP tools covering the full terminal lifecycle, plusaudit query/stats/cleanupCLI subcommands for human operators:

💡stream_paneis ideal for real-time output monitoring of long-running commands (blocking read, incremental return), replacing capture_pane polling.

Steady-state throughput:82 Mbps(1GB file, 82% link utilization on 100 Mbps link).

- BBR for private, CUBIC for public: BBR's model-based rate control tolerates packet loss without drastic window reduction (used on private-network targets); CUBIC backs off on loss for public targets. Since v0.15.0 the default isauto— see loss-adaptive below.
- Loss-adaptive congestion control:automode picks BBR for private-network targets (max throughput) and CUBIC for public targets (backs off on loss like TCP — public links at full bandwidth no longer drop the connection). Override per component:clum-cli --cc(orCLUM_CCenv), serverCLUM_CC, bridgeBRIDGE_CC.
- Receiver computes hash: Sender streams data in one pass; receiver calculates SHA256 inline — halves disk I/O on the sending side
- Unified 1MB buffer: Both MCP and Bridge useCOPY_BUF_SIZE = 1MBfortokio::io::copy_with_buf, aligned to avoid cross-boundary buffering

just check # cargo check --workspace just test # cargo test --workspace just fmt # cargo fmt --all just lint # cargo clippy --workspace -- -D warnings just build # cargo build --workspace just release-linux # cross-compile Linux x86_64 musl

- Language: Rust stable (edition 2021)
- Async runtime: tokio
- TLS: rustls (no OpenSSL dependency)
- Terminal: rmux-sdk
- Audit storage: rusqlite (bundled SQLite)
- MCP transport: stdio + Streamable HTTP (rmcp v3, JSON-RPC 2.0)

- Tool Reference— 69 MCP tools with parameters and return values
- Deployment Guide— Architecture, build, deploy, operations, security
- Terminal State Design— Terminal state awareness heuristic engine
- Contributing
- Security Policy
- Changelog

Sync Calendars, Scheduling Links, AI Executive Scheduling Assistant, Unified Calendar