Skip to main content
Glama
execkit-mcp

execkit-mcp

execkit

Persistent, structured shell sessions for AI agents, on your laptop, your servers over SSH, and your Docker containers.

CI crates.io docs.rs guide license

The execkit live viewer: sessions grouped by transport and host on the left, the selected session's timestamped shell transcript with exit codes and timings on the right

What you get that a built-in agent shell doesn't:

  • Persistent sessions on local, SSH and Docker. cd and env carry across calls, and every command returns a structured result: split stdout/stderr, exit code, duration, cwd.

  • Output that protects the agent's context. Secrets are redacted before the model sees them, and output budgets (tail, head, grep, a char cap) keep a noisy build from flooding the context window.

  • An audit trail, a live viewer, and undo. Every command can go to a JSONL audit log, you can watch sessions live in a terminal or browser (above), and remote sessions can checkpoint and restore the workspace files.

Install

Zero-install, with uv. Add this to your MCP client config:

{ "mcpServers": { "execkit": { "command": "uvx", "args": ["execkit-mcp"] } } }

Or install it and let execkit print the config for your client:

pip install execkit-mcp && execkit-mcp setup claude   # or: cursor | gemini | codex | vscode | windsurf

Then execkit-mcp doctor checks your setup. More options (prebuilt binary, cargo install, building from source) are in the Quickstart.

Status: early 0.x. The API may change between minor versions. Read Limitations before pointing it at anything important.

Related MCP server: infrastructure-mcp

Where it fits

execkit complements your agent's built-in shell or sandbox; it does not replace it. Use it when the agent needs to work on a remote host or inside a container, when you want a record of what ran, or when you want to undo file changes on a remote workspace.

The agent is the adversary. The LLM driving execkit can be prompt-injected by anything it reads, so execkit contains its own caller: a command passes the policy fence before it runs, secrets are redacted before output returns, and a changed SSH host key fails loudly instead of reconnecting into a MITM.

flowchart LR
    A([AI agent]) -->|command| F{policy fence}
    F -->|blocked| X([rejected, never runs])
    F -->|allowed| T[transport: local / SSH / Docker]
    T --> O[raw output]
    O --> R[redact secrets, bound output]
    R --> E([structured ExecResult])
    E -.-> A

Use it from an agent (MCP)

The agent gets session_create (local, ssh, or docker), session_exec, session_list and session_destroy, plus session_checkpoint / session_checkpoints / session_restore for remote undo.

State persists across calls, and every result is parsed, not scraped from a terminal:

// session_exec {"command": "cd /app && npm ci"}   -> { "exit_code": 0, "cwd": "/app" }
// session_exec {"command": "npm run build"}        // cwd is still /app
//   -> { "stderr": "Error: Cannot find module 'webpack'",
//        "exit_code": 1, "duration_ms": 3420, "cwd": "/app",
//        "truncated": false, "timed_out": false }

Commands time out after 120 seconds by default (timeout_secs per call, up to 3600). On timeout execkit interrupts the command with Ctrl-C and returns timed_out: true with exit code 124. The session keeps its cwd and env.

See crates/execkit-mcp/README.md for the operator security settings (host-key verification, key dir, audit, session limits).

Watch what the agent does

Set EXECKIT_MCP_AUDIT_DIR and every session is recorded. execkit-mcp watch shows it live in the terminal, and execkit-mcp watch --serve --open opens the read-only browser viewer shown at the top.

Transcript search with highlighted matches and a next-error button

Per-session menu with rename, pin, keep, export and screenshot; the transcript shows a failed command and a command blocked by policy

Search a transcript with / and jump between errors.

Rename, pin or keep a session, export it, or take a screenshot. Blocked commands show inline.

Use it as a library

[dependencies]
execkit = "0.9"                                           # local + SSH + Docker
# execkit = { version = "0.9", default-features = false }  # local + Docker only (no SSH; no russh/tokio)
use std::time::Duration;
use execkit::{Policy, Session};

fn main() -> Result<(), execkit::Error> {
    let mut s = Session::local()?
        .with_policy(Policy { allow: vec![], deny: vec!["rm".into()] })
        .with_timeout(Duration::from_secs(60));

    let r = s.exec("echo hi; echo err 1>&2; cd /tmp")?;
    // r.stdout == "hi"  r.stderr == "err"  r.exit_code == 0  r.cwd == "/tmp"
    println!("{} (exit {})", r.stdout, r.exit_code);

    let r = s.exec_with_timeout("sleep 30", None, Duration::from_secs(1))?;
    // r.timed_out == true  r.exit_code == 124; the session is still usable
    Ok(())
}

Runnable examples: cargo run --example local, EXECKIT_SSH="user:password@host:22" cargo run --example ssh, and EXECKIT_DOCKER=<container> cargo run --example docker.

Python

The same sessions from Python. pip install execkit (native bindings, no Rust toolchain needed):

from execkit import Session

with Session.local() as s:
    r = s.exec("echo hi; echo err >&2; cd /tmp")
    print(r.stdout, r.exit_code, r.cwd, r.stderr)   # hi 0 /tmp err

See crates/execkit-py/README.md.

What's in the box

  • Persistent, stateful sessions over local PTY, SSH, or Docker. SSH accepts host aliases from your ~/.ssh/config.

  • Structured ExecResult: split stdout/stderr, exit code, duration, cwd, truncated, timed_out.

  • Base64 command framing. Comments, heredocs, !, trailing &, syntax errors and long commands do not hang the session.

  • Timeouts that keep the session. A timed-out command is interrupted and the session carries on.

  • Secret redaction of common token shapes (AWS, GitHub, GitLab, Slack, Stripe, Google, Anthropic, OpenAI, JWTs, PEM private keys), URL passwords, password=/token=-style pairs, and values the session assigned to secret-named variables. The echoed command is redacted too.

  • Output budgets: tail/head/head+tail by line, a grep filter with context, and a char cap. Per call or a session default; the result reports what was kept.

  • Undo for agent actions on remote sessions: snapshot the workspace and restore files if a command goes wrong (needs git on the remote and an explicit workspace; files only, not side effects).

  • Audit log and live viewer, plus live MCP notifications to the client.

  • Embeddable, never a service: cargo add, in your process; no daemon, no vendor.

Upgrading to 0.9

Breaking changes from 0.8. The details are in Upgrading to 0.9.

  • SSH host keys are pinned in ~/.execkit/known_hosts, not ~/.ssh/known_hosts. Old pins are not read. The first connection re-pins, or copy them over with mkdir -p ~/.execkit && chmod 700 ~/.execkit then grep -E '^[^ ]+ SHA256:' ~/.ssh/known_hosts >> ~/.execkit/known_hosts. Old pins were keyed by bare host whatever the port: rewrite a line for a non-22 port as [host]:port, or a later port-22 connection to that host fails as a key mismatch.

  • stdin is /dev/null for every command, and pagers are set to cat.

  • The target needs base64.

  • A timeout returns exit code 124 with timed_out: true and keeps the session, instead of an error that closed it. ExecResult has a new timed_out field.

  • Session ids look like a3f9-1_local instead of 1_local.

  • SshConfig has a new connect_timeout field (default 15 s). Use SshConfig::new.

Limitations

  • Not a sandbox. The command policy is advisory string matching. It is easy to bypass: deny: ["curl"] blocks curl but not env curl, sudo curl or sh -c curl. The real control is a least-privilege environment: run the agent and SSH user with minimal rights.

  • No interactive input. stdin is /dev/null, so prompts, REPLs and editors do not work. Use non-interactive flags (sudo -n, apt-get -y). Pagers default to cat, but running less or vim directly hangs until the timeout and closes the session. Shell history is off.

  • Timeouts interrupt, they do not kill everything. execkit sends Ctrl-C. A command that ignores Ctrl-C ends the session. For long jobs, run them in the background (nohup CMD > /tmp/job.log 2>&1 &) and poll the log.

  • The target needs a POSIX shell and base64. Local sessions use bash. Windows is not supported.

  • Synchronous core. Fine for typical agent use; not tuned for thousands of concurrent sessions.

  • SSH AcceptAny host-key mode exists for testing, behind an explicit insecure opt-in. Never use it in production.

Found something rough? Open an issue.

Contributing & security

  • Contributions: see CONTRIBUTING.md.

  • Found a vulnerability? Follow SECURITY.md. Please don't open a public issue for security reports.

License

Apache-2.0: embed it freely, including commercially. See LICENSE and NOTICE.

Available Tools

7 tools
session_checkpointA

Take a workspace checkpoint on a REMOTE session (snapshot of files you can restore). Requires git on the remote host. Undoes FILES only - not side effects (DB, network, installs). Returns { checkpoint_id }.

Inputs: session_id (required), label.

session_checkpointsB
Read-only

List checkpoints (newest first) for a remote session.

Inputs: session_id (required).

session_createA

Open a stateful shell session. Prefer this over a built-in/inline shell when you need: cwd/env kept across calls, a remote host over SSH (host may be a hostname/IP or a Host alias from the operator's ssh config, <key_dir>/config, default ~/.ssh/config), a Docker container, secret-redacted output, or undoable remote file changes (checkpoints); local has no checkpoints. transport: "local"|"ssh"|"docker". ssh needs host (alias HostName/User/Port/IdentityFile fill in what you omit) + password or key_path (or an alias/default key). docker needs container. Optional fingerprint (pin host key), allow/deny. Returns session_id. Remote checkpoints need git on the remote AND an explicit workspace (set 'workspace'; otherwise off, never defaults to home); tune via auto_snapshot/paths/checkpoint_ignores. output_budget default-shapes every command's output.

Inputs: transport (required), deny, host, port, +11 more.

session_destroyA
Destructive

DESTRUCTIVE: destroy a session and free its resources. The session_id becomes invalid immediately; any unsaved shell state (cwd, env, background jobs) is lost.

Inputs: session_id (required).

session_execA
Destructive

Run a command in a session; returns ExecResult JSON (stdout, stderr, exit_code, duration_ms, cwd, truncated). Non-interactive: stdin is closed - no prompts, REPLs, or editors; use sudo -n. Default timeout 120s (EXECKIT_MCP_EXEC_TIMEOUT); timeout_secs overrides per call (max 3600). On timeout the command is interrupted (exit_code 124, timed_out:true); the session stays usable. For long jobs, background: nohup CMD > /tmp/x.log 2>&1 & then poll cat /tmp/x.log. exit, or a set -e failure, ends the shell and closes the session. Optional budget shapes output: {grep:{pattern,context?}, keep:{mode:"all"|"tail"|"head"|"head_tail",n?|head?+tail?}, max_chars?} - line-based, after redaction; never changes exit code/side effects; adds a report (mode + lines_total/lines_kept). Truncated unbudgeted output adds a hint. Redacted output is not file-accurate: never write it back to a file.

Inputs: command (required), session_id (required), budget, timeout_secs.

session_listA
Read-only

List live sessions: [{session_id, transport, idle_secs}]. Use this to recover a session_id you lost track of, or to check whether a session is still open (it may have been closed by exit, a set -e failure, or idle-timeout reaping) before calling session_exec again.

Inputs: no named parameters.

session_restoreA
Destructive

DESTRUCTIVE: restore a remote session's workspace to a checkpoint (omit checkpoint_id to restore the most recent). Reverts tracked files and DELETES untracked files anywhere under the workspace, permanently and without a prompt. Does not undo other side effects (DB writes, network calls, installs).

Inputs: session_id (required), checkpoint_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: create, exec, list, destroy, and checkpoint/restore are separate operations. The only mild ambiguity is between session_checkpoint and session_checkpoints, whose names differ only by pluralization, though their descriptions clearly distinguish taking vs listing checkpoints.

    Naming Consistency4/5

    All tools use the session_ prefix and snake_case, which is consistent and readable. The minor deviation is that session_checkpoints (list) and session_checkpoint (take) use a singular/plural distinction rather than a clear verb such as list_checkpoints, but the pattern remains largely predictable.

    Tool Count5/5

    Seven tools is a well-scoped set for managing stateful shell sessions, covering the essential lifecycle without redundancy. Each tool earns its place.

    Completeness4/5

    Core session lifecycle is covered: create, exec, list, destroy, plus checkpoint take/list/restore. Minor gaps exist, such as no explicit session info/get tool or checkpoint deletion, but the surface is sufficient for typical agent workflows.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.
      14 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to securely execute terminal commands with persistent sessions, async jobs, and mission control, while providing a live dashboard for human oversight.
      4
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Give AI agents a persistent, interactive terminal with support for SSH, REPLs, database CLIs, TUI apps, and long-running processes.
      9
      103 PyPI
      12
      MIT