microsandbox-mcp
microsandbox-mcp lets AI agents create and manage microsandboxes and execute code or file operations inside them.
Create ephemeral sandboxes to run one-off shell commands and return output.
Create, list, inspect, stop, and remove persistent sandboxes with CPU, memory, environment, volume, patch, workdir, hostname, and timeout options.
Execute commands or shell scripts inside running sandboxes.
Read, write, list, stat, create directories in, and remove files/directories inside sandboxes.
Create, list, and remove named persistent volumes with quotas.
Check whether the
msbruntime andlibkrunfware installed.Retrieve live CPU, memory, disk, and network metrics for a running sandbox.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@microsandbox-mcp run python3 -c 'print(42)' in a sandbox"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
microsandbox-mcp
Give your AI agents sandboxes. This MCP server connects any AI agent to microsandbox — letting them create fast lightweight sandboxes, execute code, manage files, and monitor resources.
Documentation | npm Package | GitHub
Installation
Run the server with npx -y microsandbox-mcp using stdio transport.
claude mcp add --transport stdio microsandbox -- npx -y microsandbox-mcpAdd to ~/.cursor/mcp.json:
{
"mcpServers": {
"microsandbox": {
"command": "npx",
"args": ["-y", "microsandbox-mcp"]
}
}
}Add to .vscode/mcp.json:
{
"servers": {
"microsandbox": {
"command": "npx",
"args": ["-y", "microsandbox-mcp"]
}
}
}Add to your config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"microsandbox": {
"command": "npx",
"args": ["-y", "microsandbox-mcp"]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"microsandbox": {
"command": "npx",
"args": ["-y", "microsandbox-mcp"]
}
}
}Add to your Zed settings:
{
"context_servers": {
"microsandbox": {
"command": {
"path": "npx",
"args": ["-y", "microsandbox-mcp"]
}
}
}
}For any MCP client that supports stdio transport:
{
"mcpServers": {
"microsandbox": {
"command": "npx",
"args": ["-y", "microsandbox-mcp"]
}
}
}Related MCP server: py-sandbox
Available Tools
Every tool returns a JSON envelope: { "ok": true, "data": ... } on success or { "ok": false, "error": ... } on failure. Large command output, logs, and file reads are capped by default and include truncation metadata when shortened.
Runtime
Tool | Description |
| Check whether the microsandbox runtime, |
| Install runtime dependencies using the microsandbox SDK installer |
Sandbox Lifecycle
Tool | Description |
| Create an ephemeral sandbox, run a shell command, return output, and remove it |
| Create and boot a persistent sandbox with rootfs, resources, process, mounts, patches, network, secrets, and lifecycle options |
| Restore a snapshot or archive as a persistent sandbox, with optional CoW memory and explicit host mappings |
| Start stopped sandboxes by name, labels, or status selector |
| List sandboxes with status, image, labels, and timestamps |
| Show status for one sandbox or a filtered sandbox set |
| Return full configuration and metadata for one sandbox |
| Stop selected sandboxes gracefully or forcefully, with optional timeout |
| Request graceful drain for selected sandboxes |
| Wait until selected sandboxes reach a terminal state |
| Remove selected stopped sandboxes, optionally force-stopping running ones first |
Restore saved execution with sandbox_restore. The MCP input remains forked for compatibility; it enables copy-on-write memory during restore and maps to the SDK’s .cowMemory(). It does not perform a live fork:
{ "name": "restored", "snapshot": "app:ready", "forked": true }Or boot only the disks from an allowlisted archive:
{ "name": "restored", "snapshot": "./ready.msnap", "diskOnly": true }Use snapshotBase for a dependent archive. Host resources are not inherited: supply volumes, ports, or vsock explicitly. externalMountPolicy (strict or relaxed) validates those mappings. Restore rejects fresh-boot settings such as CPU, memory, image, and patches; sandbox_create and sandbox_run no longer accept rootfs.kind: "snapshot".
Command Execution
Tool | Description |
| Execute an argv command with env, cwd, user, TTY, timeout, rlimits, stdin, and output caps |
| Execute a shell command string with the same execution controls |
| Start a long-running command and return an in-memory exec session id |
| Poll output events and exit status for an exec session |
| Write UTF-8 or base64 data to an exec session stdin |
| Send |
| Close and forget an exec session |
Logs
Tool | Description |
| Read captured logs with tail, time, source, grep, session id, and output cap filters |
| Poll captured logs using cursors and a bounded follow timeout |
Filesystem
Tool | Description |
| Read a sandbox file as UTF-8 text or base64 bytes |
| Write UTF-8 text or base64 bytes to a sandbox file |
| List sandbox directory entries |
| Create a sandbox directory |
| Remove a sandbox file or directory |
| Copy a file within one sandbox or between two running sandboxes |
| Rename a sandbox file or directory |
| Get sandbox path metadata |
| Check whether a sandbox path exists |
| Copy an allowlisted host path into a sandbox |
| Copy a sandbox path to an allowlisted host destination |
Metrics
Tool | Description |
| Get point-in-time metrics for one running sandbox |
| Get point-in-time metrics for all running sandboxes |
| Collect a bounded number of metrics samples from one sandbox |
Volumes
Tool | Description |
| Create a directory or disk-backed named volume with quota, capacity, and labels |
| List named volumes with kind, quota, capacity, usage, disk format, labels, and timestamps |
| Inspect one named volume |
| Remove one or more named volumes |
| Read a volume file as UTF-8 text or base64 bytes |
| Write UTF-8 text or base64 bytes to a volume file |
| List volume directory entries |
| Create a directory inside a volume |
| Remove a file or directory from a volume |
| Copy a file inside a volume |
| Rename a file or directory inside a volume |
| Get volume path metadata |
| Check whether a volume path exists |
Images
Tool | Description |
| List cached images |
| Inspect cached image config and layers |
| Remove one or more cached images, optionally forced with confirmation |
| Remove cached image artifacts unused by sandboxes, with confirmation |
Snapshots
Tool | Description |
| Create a named snapshot from a stopped sandbox, optionally into an allowlisted destination directory |
| List indexed snapshots |
| Inspect snapshot metadata by name, digest, or path, optionally verifying integrity |
| Verify recorded snapshot content integrity |
| Remove one or more snapshots, optionally forced with confirmation |
| Rebuild the local snapshot index |
| Save a snapshot to an allowlisted host archive path |
| Load a snapshot archive from an allowlisted host path |
SSH and SFTP
Tool | Description |
| Execute a command through the sandbox SSH subsystem |
| Read a file through sandbox SFTP as UTF-8 text or base64 bytes |
| Write UTF-8 text or base64 bytes through sandbox SFTP |
| Create a directory through sandbox SFTP |
| Remove a file or directory through sandbox SFTP |
| Rename a path through sandbox SFTP |
| Resolve a real path through sandbox SFTP |
| Read a symlink target through sandbox SFTP |
| Create a symlink through sandbox SFTP |
Resources
URI | Description |
| Runtime installation status and MCP configuration |
| Current sandbox inventory |
| Current volume inventory |
| Current image cache inventory |
| Current snapshot index |
| JSON Schema for sandbox creation inputs |
| Effective host path and dangerous-operation policy |
Configuration
Env var | Default | Description |
| current working directory | Colon-separated allowlist for bind mounts, host copy, snapshot save/load, and other host path operations |
|
| Set to |
|
| Enables future dangerous operations; destructive cache operations still require explicit |
|
| Default cap for command output, logs, and file reads |
|
| Default timeout budget for exec-style operations |
|
| Idle TTL for in-memory exec sessions |
| unset | Explicit backend selection: |
| unset | Select a named backend profile from |
| unset | API key used after Cloud is selected; does not select Cloud by itself |
|
| Optional endpoint override used after Cloud is selected |
| unset | Optional path to the |
| unset | Optional path to |
Cloud execution is opt-in. Set both MSB_BACKEND=cloud and MSB_API_KEY, or select a cloud profile with MSB_PROFILE/active_profile. Selecting Cloud without a usable credential returns a configuration error and never falls back to the local runtime.
The existing snapshot tools and resource continue to describe individual checkpoint artifacts. With the group-oriented SDK, they select Checkpoint; with released SDKs, they select the artifact-oriented Snapshot. Selection checks the available operations before dispatch, without invoking a mutation or retrying a failed operation through another API. Tool inputs, result fields, cloud references and host-path policy remain unchanged. This adapter does not add group-management tools.
SDK Gaps
The server intentionally stays a thin TypeScript SDK adapter and does not shell out to msb for core behavior. Image pull/load/save, persistent registry login/logout/list, SSH authorization management, and managed SSH serving are not exposed until the TypeScript SDK provides first-class APIs for them. Command aliases (msb install/msb uninstall) and runtime self-update/uninstall are intentionally out of scope.
Requirements
macOS (Apple Silicon) or Linux (x86_64/ARM64 with KVM support).
Use runtime_check to verify whether msb and libkrunfw are available. Use runtime_install to install them from the MCP server. If that fails, install manually:
curl -fsSL https://install.microsandbox.dev | shDevelopment
git clone https://github.com/superradcompany/microsandbox-mcp.git
cd microsandbox-mcp
npm install
npm run build
npm test
npm run test:e2e
node dist/index.jsnpm run test:e2e launches the built MCP server over stdio and calls every registered tool and resource with live parameters. It creates temporary sandboxes, volumes, snapshots, and host files, then cleans them up. Global image cache deletion is guarded by default; set MICROSANDBOX_MCP_E2E_DESTRUCTIVE_CACHE=1 to let the e2e script run destructive image prune behavior instead of the safe confirmation-error path.
Links
microsandbox — The microVM sandbox runtime
Documentation — Guides and API reference
Agent Skills — Teach agents to use microsandbox without MCP
License
Apache-2.0
Available Tools
19 toolscheck_installedCheck InstallationARead-onlyIdempotent
Verify that msb and libkrunfw are available on the system. Returns installation status. If not installed, the server can attempt to install them.
Inputs: no named parameters.
sandbox_createCreate SandboxA
Create and boot a persistent named sandbox with full configuration. The sandbox stays running until explicitly stopped.
Inputs: name (required), image (required), cpus, memoryMib, +8 more.
sandbox_execExecute Command in SandboxA
Execute a command inside a running sandbox and return stdout/stderr/exit code.
Inputs: name (required), command (required), args, cwd, +2 more.
sandbox_fs_listList Directory in SandboxBRead-onlyIdempotent
List directory contents inside the sandbox.
Inputs: name (required), path (required).
sandbox_fs_mkdirCreate Directory in SandboxAIdempotent
Create a directory with parent directories inside the sandbox.
Inputs: name (required), path (required).
sandbox_fs_readRead File from SandboxARead-onlyIdempotent
Read a file from the sandbox filesystem and return its contents as text.
Inputs: name (required), path (required).
sandbox_fs_removeRemove File or Directory in SandboxCDestructiveIdempotent
Remove a file or directory inside the sandbox.
Inputs: name (required), path (required).
sandbox_fs_statGet File Metadata in SandboxARead-onlyIdempotent
Get file or directory metadata (kind, size, mode, modified time) inside the sandbox.
Inputs: name (required), path (required).
sandbox_fs_writeWrite File to SandboxAIdempotent
Write content to a file inside the sandbox. Creates parent directories as needed.
Inputs: name (required), path (required), content (required).
sandbox_inspectInspect SandboxARead-onlyIdempotent
Get detailed information about a specific sandbox including full configuration.
Inputs: name (required).
sandbox_listList SandboxesARead-onlyIdempotent
List all sandboxes with their status.
Inputs: no named parameters.
sandbox_metricsGet Sandbox MetricsARead-onlyIdempotent
Get live resource usage metrics (CPU, memory, disk, network) for a running sandbox.
Inputs: name (required).
sandbox_removeRemove SandboxADestructiveIdempotent
Remove a sandbox. Must be stopped unless force is true.
Inputs: name (required), force.
sandbox_runRun Command in Ephemeral SandboxA
Create an ephemeral sandbox, run a shell command, return the output, and destroy the sandbox. Best for quick one-off tasks like running a script, checking a command, or testing code.
Inputs: image (required), command (required), memoryMib, cpus, +1 more.
sandbox_shellRun Shell Command in SandboxA
Execute a shell command or script string inside a running sandbox. Interprets pipes, redirects, and shell syntax.
Inputs: name (required), command (required), timeout.
sandbox_stopStop SandboxADestructive
Stop a running sandbox. Use force to kill with SIGKILL instead of graceful SIGTERM.
Inputs: name (required), force.
volume_createCreate VolumeA
Create a named persistent volume. Volumes survive sandbox restarts and can be shared across sandboxes.
Inputs: name (required), sizeMib.
volume_listList VolumesARead-onlyIdempotent
List all named volumes.
Inputs: no named parameters.
volume_removeRemove VolumeBDestructiveIdempotent
Remove a named volume.
Inputs: name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool targets a distinct operation with clear prefixes (sandbox_, volume_, check_installed). The subtle overlap between sandbox_exec and sandbox_shell is resolved by their descriptions (command vs shell syntax).
All tool names follow a consistent verb_pattern: sandbox_<action> for sandbox tools, volume_<action> for volume tools, and check_installed conforms to verb_noun. No mixing of conventions.
19 tools cover sandbox lifecycle, filesystem operations, and volume management comprehensively. While slightly above the typical 3-15 range, the count is justified by the breadth of functionality.
The tool set covers the full sandbox lifecycle (create, run, exec, shell, stop, remove), filesystem operations, monitoring via metrics, and volume management. No obvious gaps for the domain.
Maintenance
Related MCP Connectors
Secure Linux sandboxes for AI agents, as MCP tools.
Linux microVM sandboxes for AI agents: run commands, files, processes, pause and wake.
Cloud Linux VMs for your agent: run code, Docker, files and HTTPS previews in a Sandboxer microVM.
Run AI agent tasks in isolated sandboxes with a cost cap, saved workflows and scoped connections.
Related MCP Servers
- AlicenseBqualityDmaintenanceExposes Arrakis VM sandbox functionality to LLMs, enabling sandbox management and command execution.911AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to execute arbitrary Python code securely in a sandboxed environment with resource limits and security constraints via MCP protocol.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, manage, and execute code in isolated Firecracker microVM sandboxes via the MCP protocol, with support for sandbox lifecycle and file operations.4Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to safely execute Python, JavaScript, and Bash code in an isolated Docker sandbox with strict security constraints.1-