Skip to main content
Glama

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-mcp

Add 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

runtime_check

Check whether the microsandbox runtime, msb, and libkrunfw are available

runtime_install

Install runtime dependencies using the microsandbox SDK installer

Sandbox Lifecycle

Tool

Description

sandbox_run

Create an ephemeral sandbox, run a shell command, return output, and remove it

sandbox_create

Create and boot a persistent sandbox with rootfs, resources, process, mounts, patches, network, secrets, and lifecycle options

sandbox_restore

Restore a snapshot or archive as a persistent sandbox, with optional CoW memory and explicit host mappings

sandbox_start

Start stopped sandboxes by name, labels, or status selector

sandbox_list

List sandboxes with status, image, labels, and timestamps

sandbox_status

Show status for one sandbox or a filtered sandbox set

sandbox_inspect

Return full configuration and metadata for one sandbox

sandbox_stop

Stop selected sandboxes gracefully or forcefully, with optional timeout

sandbox_drain

Request graceful drain for selected sandboxes

sandbox_wait

Wait until selected sandboxes reach a terminal state

sandbox_remove

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

sandbox_exec

Execute an argv command with env, cwd, user, TTY, timeout, rlimits, stdin, and output caps

sandbox_shell

Execute a shell command string with the same execution controls

sandbox_exec_start

Start a long-running command and return an in-memory exec session id

sandbox_exec_poll

Poll output events and exit status for an exec session

sandbox_exec_write_stdin

Write UTF-8 or base64 data to an exec session stdin

sandbox_exec_signal

Send hup, int, term, kill, or a numeric signal to an exec session

sandbox_exec_close

Close and forget an exec session

Logs

Tool

Description

sandbox_logs_read

Read captured logs with tail, time, source, grep, session id, and output cap filters

sandbox_logs_stream

Poll captured logs using cursors and a bounded follow timeout

Filesystem

Tool

Description

sandbox_fs_read

Read a sandbox file as UTF-8 text or base64 bytes

sandbox_fs_write

Write UTF-8 text or base64 bytes to a sandbox file

sandbox_fs_list

List sandbox directory entries

sandbox_fs_mkdir

Create a sandbox directory

sandbox_fs_remove

Remove a sandbox file or directory

sandbox_fs_copy

Copy a file within one sandbox or between two running sandboxes

sandbox_fs_rename

Rename a sandbox file or directory

sandbox_fs_stat

Get sandbox path metadata

sandbox_fs_exists

Check whether a sandbox path exists

sandbox_fs_copy_from_host

Copy an allowlisted host path into a sandbox

sandbox_fs_copy_to_host

Copy a sandbox path to an allowlisted host destination

Metrics

Tool

Description

sandbox_metrics

Get point-in-time metrics for one running sandbox

sandbox_metrics_all

Get point-in-time metrics for all running sandboxes

sandbox_metrics_stream

Collect a bounded number of metrics samples from one sandbox

Volumes

Tool

Description

volume_create

Create a directory or disk-backed named volume with quota, capacity, and labels

volume_list

List named volumes with kind, quota, capacity, usage, disk format, labels, and timestamps

volume_inspect

Inspect one named volume

volume_remove

Remove one or more named volumes

volume_fs_read

Read a volume file as UTF-8 text or base64 bytes

volume_fs_write

Write UTF-8 text or base64 bytes to a volume file

volume_fs_list

List volume directory entries

volume_fs_mkdir

Create a directory inside a volume

volume_fs_remove

Remove a file or directory from a volume

volume_fs_copy

Copy a file inside a volume

volume_fs_rename

Rename a file or directory inside a volume

volume_fs_stat

Get volume path metadata

volume_fs_exists

Check whether a volume path exists

Images

Tool

Description

image_list

List cached images

image_inspect

Inspect cached image config and layers

image_remove

Remove one or more cached images, optionally forced with confirmation

image_prune

Remove cached image artifacts unused by sandboxes, with confirmation

Snapshots

Tool

Description

snapshot_create

Create a named snapshot from a stopped sandbox, optionally into an allowlisted destination directory

snapshot_list

List indexed snapshots

snapshot_inspect

Inspect snapshot metadata by name, digest, or path, optionally verifying integrity

snapshot_verify

Verify recorded snapshot content integrity

snapshot_remove

Remove one or more snapshots, optionally forced with confirmation

snapshot_reindex

Rebuild the local snapshot index

snapshot_save

Save a snapshot to an allowlisted host archive path

snapshot_load

Load a snapshot archive from an allowlisted host path

SSH and SFTP

Tool

Description

sandbox_ssh_exec

Execute a command through the sandbox SSH subsystem

sandbox_sftp_read

Read a file through sandbox SFTP as UTF-8 text or base64 bytes

sandbox_sftp_write

Write UTF-8 text or base64 bytes through sandbox SFTP

sandbox_sftp_mkdir

Create a directory through sandbox SFTP

sandbox_sftp_remove

Remove a file or directory through sandbox SFTP

sandbox_sftp_rename

Rename a path through sandbox SFTP

sandbox_sftp_realpath

Resolve a real path through sandbox SFTP

sandbox_sftp_readlink

Read a symlink target through sandbox SFTP

sandbox_sftp_symlink

Create a symlink through sandbox SFTP

Resources

URI

Description

microsandbox://runtime

Runtime installation status and MCP configuration

microsandbox://sandboxes

Current sandbox inventory

microsandbox://volumes

Current volume inventory

microsandbox://images

Current image cache inventory

microsandbox://snapshots

Current snapshot index

microsandbox://schemas/sandbox-create

JSON Schema for sandbox creation inputs

microsandbox://policy

Effective host path and dangerous-operation policy

Configuration

Env var

Default

Description

MICROSANDBOX_MCP_HOST_PATHS

current working directory

Colon-separated allowlist for bind mounts, host copy, snapshot save/load, and other host path operations

MICROSANDBOX_MCP_HOST_PATH_POLICY

allowlist

Set to unrestricted to allow any host path

MICROSANDBOX_MCP_ENABLE_DANGEROUS

0

Enables future dangerous operations; destructive cache operations still require explicit confirm: true

MICROSANDBOX_MCP_MAX_OUTPUT_BYTES

1048576

Default cap for command output, logs, and file reads

MICROSANDBOX_MCP_DEFAULT_TIMEOUT_MS

120000

Default timeout budget for exec-style operations

MICROSANDBOX_MCP_SESSION_TTL_MS

900000

Idle TTL for in-memory exec sessions

MSB_BACKEND

unset

Explicit backend selection: local or cloud

MSB_PROFILE

unset

Select a named backend profile from ~/.microsandbox/config.json

MSB_API_KEY

unset

API key used after Cloud is selected; does not select Cloud by itself

MSB_API_URL

https://api.microsandbox.dev

Optional endpoint override used after Cloud is selected

MSB_PATH

unset

Optional path to the msb binary for SDK/runtime discovery

MSB_LIBKRUNFW_PATH

unset

Optional path to libkrunfw

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 | sh

Development

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.js

npm 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.

License

Apache-2.0

Available Tools

19 tools
check_installedCheck InstallationA
Read-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 SandboxB
Read-onlyIdempotent

List directory contents inside the sandbox.

Inputs: name (required), path (required).

sandbox_fs_mkdirCreate Directory in SandboxA
Idempotent

Create a directory with parent directories inside the sandbox.

Inputs: name (required), path (required).

sandbox_fs_readRead File from SandboxA
Read-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 SandboxC
DestructiveIdempotent

Remove a file or directory inside the sandbox.

Inputs: name (required), path (required).

sandbox_fs_statGet File Metadata in SandboxA
Read-onlyIdempotent

Get file or directory metadata (kind, size, mode, modified time) inside the sandbox.

Inputs: name (required), path (required).

sandbox_fs_writeWrite File to SandboxA
Idempotent

Write content to a file inside the sandbox. Creates parent directories as needed.

Inputs: name (required), path (required), content (required).

sandbox_inspectInspect SandboxA
Read-onlyIdempotent

Get detailed information about a specific sandbox including full configuration.

Inputs: name (required).

sandbox_listList SandboxesA
Read-onlyIdempotent

List all sandboxes with their status.

Inputs: no named parameters.

sandbox_metricsGet Sandbox MetricsA
Read-onlyIdempotent

Get live resource usage metrics (CPU, memory, disk, network) for a running sandbox.

Inputs: name (required).

sandbox_removeRemove SandboxA
DestructiveIdempotent

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 SandboxA
Destructive

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 VolumesA
Read-onlyIdempotent

List all named volumes.

Inputs: no named parameters.

volume_removeRemove VolumeB
DestructiveIdempotent

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

    A3.8/5.0

    Scored across 19 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to execute arbitrary Python code securely in a sandboxed environment with resource limits and security constraints via MCP protocol.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      4
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to safely execute Python, JavaScript, and Bash code in an isolated Docker sandbox with strict security constraints.
      1
      -