Wrap a sandbox as an MCP tool handler

You write the MCP server; BoxLite supplies the sandbox behind it. An MCP tool handler calls SimpleBox.exec(...) and returns the result — nothing in the pattern is BoxLite-specific except the two lines that start the box.

Quick Example

This is the sandbox half — the function you register as an MCP tool. It is complete and runnable on its own.

import asyncio

from boxlite import SimpleBox, BoxliteError

async def run_in_sandbox(command: str, *args: str) -> dict:
    """Run one command in an isolated sandbox and return a serializable result."""
    try:
        # auto_remove=True tears the box down on exit; image is required
        async with SimpleBox(image="alpine:latest", auto_remove=True) as box:
            result = await box.exec(command, *args, timeout=30.0)
            # A non-zero exit code does NOT raise — return it as data
            return {
                "exit_code": result.exit_code,
                "stdout": result.stdout,
                "stderr": result.stderr,
            }
    except BoxliteError as exc:
        # Wrapper-layer errors (e.g. ExecError) subclass BoxliteError
        return {"error": str(exc)}
    except RuntimeError as exc:
        # Image pull failures and missing virtualization surface as RuntimeError
        return {"error": f"runtime failure: {exc}"}

async def main() -> None:
    print(await run_in_sandbox("echo", "hello from the box"))

if __name__ == "__main__":
    asyncio.run(main())

To make it an actual MCP tool, register it with a standalone MCP framework — for example FastMCP from the official mcp Python package, installed separately. The full build, including a client that performs the handshake, is in the use cases: Expose a sandbox as an MCP tool.

Parameters and Returns

The MCP layer has no BoxLite-specific parameters. The table below covers the SimpleBox.exec surface used above so this page stands alone.

Parameter	Required	Type	Notes
`image` (constructor)	Yes (or `rootfs_path`)	`str`	Container image to boot, e.g. `"alpine:latest"`
`auto_remove` (constructor)	No	`bool`	Default `True`. Remove the box on exit
`cmd` (first arg to `exec`)	Yes	`str`	Executable to run
`*args`	No	`str`	Command arguments
`timeout`	No	`float`	Seconds. `SimpleBox.exec` uses `timeout`; the native `Box.exec` uses `timeout_secs`
`env`	No	`dict[str, str]`	A dict, not a list

exec returns an ExecResult:

Field	Type	Notes
`exit_code`	`int`	A non-zero value does not raise — check it yourself
`stdout`	`str`	Captured standard output
`stderr`	`str`	Captured standard error
`error_message`	`str \| None`	Set only when the process died abnormally

SkillBox starts the in-box Claude CLI with an MCP config file, so the agent inside the sandbox can talk to MCP servers. That path configures the agent, not a host-side endpoint — see Run Claude Code.

Troubleshooting

Symptom	Cause	Fix
`ModuleNotFoundError: No module named 'boxlite.mcp'`	The MCP layer lives in your own code, not in the SDK	Use your MCP framework and wrap `SimpleBox.exec` as shown above
The tool returned `exit_code: 1` with no exception	`exec` does not raise on a non-zero exit	Inspect `result.exit_code` and pass it back to the client
`RuntimeError` instead of `BoxliteError`	Missing virtualization or an image pull failure	Catch `RuntimeError` separately and retry
`ModuleNotFoundError: No module named '@boxlite-ai/boxlite'` (Node)	Wrong package name	The Node package is `@boxlite-ai/boxlite`, not `boxlite`

Expose a sandbox as an MCP tool — the end-to-end build with a real client handshake.
Run Python code in a box — the execution primitives behind the tools.
Secrets and hardening — inject an MCP server’s API key safely.

​Quick Example

​Parameters and Returns

​Related capability: MCP inside the box

​Troubleshooting

​Related

Quick Example

Parameters and Returns

Related capability: MCP inside the box

Troubleshooting

Related