execkit-mcp
One line: execkit-mcp lets an AI agent open persistent shell sessions on your machine, remote hosts over SSH, or Docker containers, run commands in them, and take/restore file checkpoints.
Create sessions (
session_create) over three transports:local,ssh(host, user, pluspasswordorkey_path), ordocker(running container name/id).Run commands (
session_exec) and get structured results: split stdout/stderr, exit code, duration, cwd, and truncation flag — state (cwd, env) persists across calls.Shape output with a budget (
grepregex + context,keepinall/tail/head/head_tailmode,max_charscap) per call or as a session default; secrets are redacted before shaping.Fence commands with optional
allow/denyprogram lists and pin SSH host keys viafingerprint.Checkpoint remote workspaces (
session_checkpoint,session_checkpoints) — requiresgiton the remote and an explicitworkspace; files only, not side effects.Restore/undo files (
session_restore) to a given or the most recent checkpoint.Auto-snapshot before changing remote commands, with
pathsandcheckpoint_ignoresto control what's captured.Tear down sessions (
session_destroy) to free resources.
Provides the ability to execute commands inside Docker containers via persistent sessions, with structured results, security controls, and support for checkpoint/restore.
execkit
Persistent, structured shell sessions for AI agents, on your laptop, your servers over SSH, and your Docker containers.

What you get that a built-in agent shell doesn't:
Persistent sessions on local, SSH and Docker.
cdand 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 | windsurfThen 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 -.-> AUse 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.
|
|
Search a transcript with | 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 errSee 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+tailby line, agrepfilter 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
giton 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 withmkdir -p ~/.execkit && chmod 700 ~/.execkitthengrep -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/nullfor every command, and pagers are set tocat.The target needs
base64.A timeout returns exit code 124 with
timed_out: trueand keeps the session, instead of an error that closed it.ExecResulthas a newtimed_outfield.Session ids look like
a3f9-1_localinstead of1_local.SshConfighas a newconnect_timeoutfield (default 15 s). UseSshConfig::new.
Limitations
Not a sandbox. The command policy is advisory string matching. It is easy to bypass:
deny: ["curl"]blockscurlbut notenv curl,sudo curlorsh -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 tocat, but runninglessorvimdirectly 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 usebash. Windows is not supported.Synchronous core. Fine for typical agent use; not tuned for thousands of concurrent sessions.
SSH
AcceptAnyhost-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 toolssession_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_checkpointsBRead-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_destroyADestructive
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_execADestructive
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_listARead-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_restoreADestructive
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
Scored across 7 tools
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.
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.
Seven tools is a well-scoped set for managing stateful shell sessions, covering the essential lifecycle without redundancy. Each tool earns its place.
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
Related MCP Connectors
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Persistent Linux computers for AI agents: desktop, signed-in browser, vault, apps and shell.
Cloud desktops for AI agents: create a Linux computer, see its screen, click, type and run tasks.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.14 npm2MIT
- AlicenseBqualityBmaintenanceGive Claude Code, Cursor, and other AI agents safe access to your real infrastructure — without giving them raw SSH access.375MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to securely execute terminal commands with persistent sessions, async jobs, and mission control, while providing a live dashboard for human oversight.4Apache 2.0
- AlicenseAqualityCmaintenanceGive AI agents a persistent, interactive terminal with support for SSH, REPLs, database CLIs, TUI apps, and long-running processes.9103 PyPI12MIT

