Skip to main content
Glama
blinkingbit-oss

execkit-mcp

by blinkingbit-oss
OverviewSchemaRelated ServersScoreDiscussions
Rust
Local

execkit

Stateful, structured, safe command execution for AI agents - over local shells, SSH, and Docker.

CI crates.io docs.rs guide license

Early 0.x release - not production-ready. See Limitations.

execkit gives an AI agent a persistent session on a machine - a local shell, an SSH host, or a Docker container - and returns a structured result for every command. Crucially, it treats the agent itself as untrusted: every command passes a policy fence, output is scrubbed of secrets, and flooding output is bounded. Use it as an embeddable Rust library or as an MCP server any agent can drive.

Why

Letting an autonomous agent run shell commands is useful but risky: built-in agent shells are local-only with no guardrails, managed sandboxes lock you in, and raw SSH is stateless-per-command with no notion of "is this command allowed?"

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

Related MCP server: mcp-ssh-terminal

Use it from an agent (MCP)

Install the server - no Rust toolchain needed:

# pip (the server binary ships as a wheel):
pip install execkit-mcp

# ...or a prebuilt binary (Linux/macOS, x86_64 + arm64):
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/blinkingbit-oss/execkit/releases/latest/download/execkit-mcp-installer.sh | sh

# ...or with cargo:
cargo install execkit-mcp

Point your MCP client at it (claude mcp add execkit -- execkit-mcp, or a config block):

{ "mcpServers": { "execkit": { "command": "execkit-mcp" } } }

The agent gets session_create (local, ssh, or docker) -> session_exec -> session_destroy, plus session_checkpoint/session_restore for remote undo. session_exec returns a structured ExecResult (split stdout/stderr, exit code, cwd), already secret-redacted and bounded.

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 }

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

Use it as a library

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

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

    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);
    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, Policy

with Session.local(policy=Policy(deny=["rm"]), timeout=30.0) as s:
    r = s.exec("cd /app && npm ci")
    print(r.stdout, r.exit_code, r.cwd)

See crates/execkit-py/README.md.

What you get

  • Persistent, stateful sessions - cd/env/state persist across commands, over local PTY, SSH, or Docker.

  • Structured ExecResult - split stdout/stderr, exit code, duration, cwd.

  • Safe by construction - advisory command policy, secret redaction, bounded (anti-flood) output, SSH host-key verification.

  • One small API, every transport - the same ExecResult regardless of transport.

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

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

  • Output budgets - shape any command's output so huge logs do not blow the agent's context: 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.

Limitations

An early library - today:

  • Not a sandbox. The command policy is an advisory tripwire (string-matching, bypassable). The load-bearing control is a least-privilege environment - run the agent and SSH user with minimal rights.

  • A timed-out command poisons the session - you get a clear error and should create a new session.

  • Unix-only. Local sessions need a POSIX shell (bash); Windows is later.

  • 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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
labelNoOptional human label for the checkpoint.
session_idYesSession id from session_create.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. It discloses dependencies (git), scope (files only), and return format ({checkpoint_id}). Could add detail on persistence or failure modes, but sufficient for safe usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences that front-load the purpose and immediately add requirements and limitations. Every phrase adds value; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

In the absence of an output schema, the description specifies the return value. It explains what the tool does and its constraints. Missing details on checkpoint lifecycle or restoration, but adequate for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters have descriptions. The description adds no extra parameter-specific meaning beyond what the schema provides, meeting the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it takes a workspace checkpoint (snapshot of files) on a remote session. It clarifies it's a file-only operation and distinguishes from sibling tools by emphasizing its scope and requirement for git.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: requires git on remote host, undoes files only, no side effects. Implies when to use (file snapshot) but does not explicitly contrast with siblings like session_restore or session_checkpoints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_checkpointsA

List checkpoints (newest first) for a remote session.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYesSession id from session_create.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses ordering behavior but does not explicitly state that the operation is read-only or describe other traits like pagination or data limits. For a simple listing tool, this is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that conveys the purpose efficiently without any wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (1 parameter, no output schema, no annotations), the description is functional. However, it lacks details about return format or what fields each checkpoint contains, which would be helpful for an agent to fully understand usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter session_id, which is already described as 'Session id from session_create.' The tool description adds no additional parameter meaning, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List', the resource 'checkpoints for a remote session', and the ordering 'newest first'. This distinguishes it from sibling tools like session_checkpoint (likely single checkpoint) and session_create.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing to list checkpoints for a session, but does not provide explicit guidance on when to use this tool versus alternatives like session_checkpoint, nor does it mention any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_createA

Open a stateful shell session. transport is "local", "ssh", or "docker". ssh needs host, user, and password or key_path; docker needs container (a running container name/id). Optional fingerprint (pin host key), allow/deny command lists. Returns a session_id. Remote sessions support workspace checkpoints - requires git on the remote AND an explicit workspace (set 'workspace'; without it checkpoints/auto_snapshot are disabled, never defaulting to the home dir). Tune with auto_snapshot, paths, checkpoint_ignores. Pass output_budget (same shape as session_exec's budget) to default-shape every command's output.

ParametersJSON Schema
NameRequiredDescriptionDefault
denyNoOptional command denylist (program names).
hostNoSSH host (required for ssh).
portNoSSH port (default 22).
userNoSSH user (required for ssh).
allowNoOptional command allowlist (program names). If set, only these run.
pathsNoSub-paths under the root to checkpoint (optional; default: whole root).
key_pathNoSSH private-key path (must live under the operator's key dir).
passwordNoSSH password auth.
containerNoDocker container name or id (required for docker).
transportYesTransport: "local" (a local shell), "ssh", or "docker".
workspaceNoRemote workspace root for checkpoints. REQUIRED to enable checkpoints; there is no default (it will not snapshot the cwd/home dir).
fingerprintNoOptional pinned host-key fingerprint ("SHA256:..."). If set, the server requires the host key to match exactly. Otherwise the operator's known_hosts file is used.
auto_snapshotNoAuto-snapshot before changing remote commands (default true, but only takes effect once `workspace` is set; remote only).
output_budgetNoDefault output budget for every exec in this session (optional).
checkpoint_ignoresNoExtra exclude patterns (gitignore syntax) added to the snapshot, on top of the built-in defaults (.git, node_modules, caches, .ssh, ...).

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses key behaviors: session creation, transport auth, workspace requirement for remote checkpoints, auto_snapshot dependency, output_budget. It does not cover error scenarios but is otherwise transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph that front-loads purpose. It could be more structured with bullet points for transport types, but it is efficient and contains no extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 15 parameters (1 required) and no output schema, the description covers critical behaviors: transport specifics, workspace/checkpoint rules, output_budget. It lacks details on session_id format or error handling, but is adequate for tool selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant meaning: explains combined parameter requirements (e.g., transport + host/user/password/key_path), workspace necessity for checkpoints, and output_budget reuse from session_exec. This goes beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Open a stateful shell session' and specifies the three transport types. It distinguishes itself from sibling tools (session_destroy, session_exec) by being the creation action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description enumerates requirements for each transport (ssh needs host/user/password or key_path, docker needs container) and explains workspace/checkpoint conditions. It lacks explicit 'when not to use' but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_destroyB

Destroy a session and free its resources.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYesSession id from session_create.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description lacks behavioral details beyond 'destroy' and 'free its resources.' No annotations are present to fill the gap; key information like irreversibility, required permissions, or side effects on other sessions is omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently conveys the core action. However, it sacrifices completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with no output schema, the description should provide more context about return values, error behavior, or post-destroy state. It is under-specified given the lack of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (the one parameter is described in the schema as 'Session id from session_create'). The description adds no additional semantic meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Destroy a session') and the resource ('session'), with the added detail of freeing resources. It distinguishes from sibling tools like session_create or session_checkpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., session_checkpoint or session_restore). There is no mention of prerequisites or context such as needing an active session.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_execA

Run a command in a session; returns a structured ExecResult JSON (stdout, stderr, exit_code, duration_ms, cwd, truncated). Optionally pass budget to shape output: {grep:{pattern,context?}, keep:{mode:"all"|"tail"|"head"|"head_tail",n?|head?+tail?}, max_chars?}. Shaping is line-based, client-side, AFTER secret redaction; it never changes the exit code or side effects. When applied, the result includes a budget report (per-stream mode + lines_total/lines_kept).

ParametersJSON Schema
NameRequiredDescriptionDefault
budgetNoShape THIS command's output (overrides the session default).
commandYesThe shell command to run.
session_idYesSession id from session_create.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the output shaping behavior (line-based, client-side, after secret redaction, no effect on exit code/side effects) and the inclusion of a budget report. Since no annotations exist, this adds value, but it omits details on error handling, session state mutations beyond shaping, and environment assumptions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (5 sentences) and front-loaded with the core purpose. Each sentence provides essential detail: return format, budget parameter structure, behavioral guarantees. No wasted words; clear and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 3 parameters, no output schema, and no annotations, the description covers the return format, budget parameter details, and key behavioral traits. However, it does not explain error cases, session lifecycle prerequisites (session_id from session_create), or the execution environment (cwd, env), which would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds significant meaning by explaining the budget structure (grep, keep, max_chars), processing order, client-side execution, and the budget report, which goes beyond the schema's static definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Run a command in a session' with a specific verb and resource, and details the return format (structured ExecResult JSON). Among sibling tools (session_create, session_destroy, etc.), this is the only command execution tool, making its purpose distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly indicates use for executing commands in a session, but lacks explicit when-to-use or when-not-to-use guidance or alternatives. With clear sibling names, the context is sufficient, but no exclusions or comparisons are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_restoreA

Restore a remote session's workspace FILES to a checkpoint (omit checkpoint_id to restore the most recent). Does not undo side effects.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYesSession id from session_create.
checkpoint_idNoCheckpoint id to restore; omit to restore the most recent.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool 'does not undo side effects,' which is a crucial behavioral detail. However, with no annotations provided, it could further clarify whether the operation is destructive, idempotent, or requires an active session.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loading the core functionality and then adding a key behavioral caveat. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description is largely sufficient. It explains the main action, default behavior, and a limitation (side effects). A minor gap is the lack of information about return values or error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters are fully described in the input schema (100% coverage). The description adds minimal value beyond the schema, mainly reiterating the default behavior for checkpoint_id. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action ('restore'), the target resource ('remote session's workspace files'), and a key condition ('omit checkpoint_id to restore the most recent'). This distinguishes it from sibling tools like session_checkpoint (create) and session_destroy (destroy).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning the default behavior for checkpoint_id, but it does not explicitly state when to choose this tool over siblings or any prerequisites or limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.8.0
    • First observedsession_checkpoint
    • First observedsession_checkpoints
    • First observedsession_create
    • First observedsession_destroy
    • First observedsession_exec
    • First observedsession_restore
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: create, destroy, exec, checkpoint, list checkpoints, and restore. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent `session_verb` pattern (e.g., session_create, session_exec, session_checkpoint), making the pattern predictable.

Tool Count5/5

Six tools is well-scoped for the session management domain, covering the core lifecycle and checkpoint functionality without bloat.

Completeness4/5

Covers session creation, execution, destruction, and checkpoint CRUD. Minor gap: no tool to list all sessions, but the set is still quite complete for typical usage.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Interactive Terminal MCP

    Vltja
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides AI agents with fully interactive terminal sessions, including TUI support, keyboard control, and screen capture across Windows, Linux, and Mac.
    MIT

  • mcp-ssh-terminal

    zhdkirill
    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.
    23
    1
    MIT

  • Remote SSH MCP

    the-nine-nation
    A
    license
    A
    quality
    A
    maintenance
    Exposes persistent, stateful remote Bash sessions to AI agents via SSH, enabling command execution with preserved working directory and environment.
    7
    52
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/blinkingbit-oss/execkit'

If you have feedback or need assistance with the MCP directory API, please join our Discord server