blinkingbit-oss/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.** 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:
Or install it and let execkit print the config for your client:
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.
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.
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:
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 / 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
Runnable examples: cargo run --example local,
EXECKIT_SSH="user:password@host:22" cargo run --example ssh, and
EXECKIT_DOCKER= cargo run --example docker.
Python
The same sessions from Python. pip install execkit (native bindings, no Rust
toolchain needed):
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,