kosa8

kosa8 / Guides

Guide · Updated 2026-10-31

How do I run MCP servers in a sandbox?

An MCP server is a program you download and run, and when an AI client launches it the usual way (with npx, uvx or pip) it runs as you, with your files, SSH keys and network. To sandbox it, start it inside an isolated machine that cannot see your home directory and can reach only the hosts it needs, and put a gateway between it and your AI client. With kosa8, kosa8 mcp add registers a server to run in its own microVM, and kosa8 mcp serve is the one MCP endpoint your client talks to.

01Steps

  1. Install kosa8. On an Apple silicon Mac or x86-64 Linux:

  2. Register the server with its image, network and tools. Name the container image it runs in, the only hosts it may reach, and the tools to expose. Everything after -- is the server's own command line. An npx server downloads itself first, hence the npm registry. Registration only writes an entry to ~/.kosa8/mcp-servers.json; nothing runs yet.

    terminal
    kosa8 mcp add github --image node:22-alpine \
    --egress-allow api.github.com --egress-allow registry.npmjs.org \
    -e GITHUB_TOKEN=... \
    --allow-tool list_issues --allow-tool create_issue \
    -- npx -y @modelcontextprotocol/server-github

  3. Check what is registered.

  4. Point your AI client at the gateway. Configure one MCP server, the command kosa8 mcp serve, over stdio. In Claude Code that is the first line below; clients that read an mcpServers JSON file take the second form. On start the gateway boots each registered server in a sandbox named mcp-NAME and asks it for its tools.

    terminal
    { "mcpServers": { "kosa8": { "command": "kosa8", "args": ["mcp", "serve"] } } }

  5. Review a tool whose definition changed. If a server later changes a tool's description or schema, the gateway withholds that tool and prints a line saying so. Read the change, then accept it at a terminal.

    terminal
    kosa8 mcp pins diff github
kosa8 mcp pins approve github

  6. Read the audit log. Every call to a third-party server is recorded as an mcp.decision entry, and an allowed call also gets an mcp.result entry.

    terminal
    kosa8 audit ls
kosa8 audit verify

02Why is an MCP server a security risk?

An MCP server is arbitrary code that runs with the privileges of whoever starts it. The MCP specification's security best practices list arbitrary code execution, data exfiltration and data loss as risks of local MCP servers, and recommend running them in a sandboxed environment with minimal default privileges and restricted access to the file system and network.

Two more problems sit on top of that. Supply chain: a config line such as npx -y some-server fetches and runs whatever version the registry serves at that moment, so a compromised package or a typo-squatted name runs on your machine the next time the client starts. The words are instructions: the model reads every tool's name and description before deciding what to do, so whoever controls a server controls text your assistant follows.

03What is tool poisoning in MCP?

Tool poisoning is hiding instructions for the model inside a tool's description or schema, for example telling it to read a private key and pass it in an argument. A related attack, sometimes called a rug pull, serves a harmless description when you approve the tool and a different one later under the same name.

A sandbox limits what the server process can touch, but a poisoned description acts through the model, which may call other tools that can. That is why kosa8 pairs the sandbox with pins. The first time the gateway sees a server it records a SHA-256 digest over each tool's name, title, description, input schema, output schema and annotations. A tool whose digest later differs, or a new tool, is withheld from the model until a person runs kosa8 mcp pins approve at a terminal; run from a script or pipe, approve refuses. Arguments are checked against the pinned input schema on the way in, and results against a declared output schema on the way out.

04What does the kosa8 sandbox isolate?

Each registered server runs as a container in its own kosa8 microVM, with its own kernel and the network rule you gave it. It cannot see your files, the other servers, or kosa8's own state.

  • Network. --egress-allow permits only the hosts or *.domain wildcards you list. Without --egress or --egress-allow the default is any, unless your organisation's policy sets default_egress, so name the hosts.
  • Tools. --allow-tool exposes only the named tools. A tool whose name collides with an existing one is skipped.
  • Audit. Arguments and results are recorded by SHA-256 digest, never stored.

Limits: first-use definitions are trusted as they are (an organisation can pin digests in a signed policy instead); results are checked for shape, not meaning; nothing scans for prompt injection; the gateway runs as you; and -e values can be sent to any host the server may reach.

05Can an AI agent get sandboxes as MCP tools?

Yes. The same kosa8 mcp serve gateway also serves thirty tools that drive kosa8 itself, including sandbox_create, sandbox_run, sandbox_checkpoint, sandbox_rewind and sandbox_fork, so an agent can make its own isolated machine for risky work and undo it.

A sandbox an agent creates with sandbox_create has no network unless it asks for one, by naming hosts in egress_allow or asking for egress: "any"; the request is in the call's arguments, so it is in the audit entry. Images can still be pulled, because the service fetches them on the host side. The assistant cannot share any host directory unless you start the gateway with --allow-mount DIR (read-only, or DIR:rw). List the tools and their descriptions with:

06Other options

  • Docker MCP Toolkit. Docker Desktop's MCP Toolkit runs servers from Docker's MCP Catalog as containers and connects them to clients. A fit for teams already on Docker Desktop.
  • Your own container. Running a server with docker run -i --rm and a client config that launches it keeps it off your files, with container isolation and a shared kernel. Add --network none for servers that need no network.
  • A full VM in UTM or Lima. Put the AI client and its servers together in one Linux VM. Strong isolation, but you work inside the VM.
  • gVisor, Firecracker or Kata Containers. Building blocks for hosting MCP servers on Linux servers you run, with a user-space kernel (gVisor) or a microVM per workload (Firecracker, Kata).
  • Claude Code's built-in sandbox. /sandbox restricts the file system and network for the commands Claude Code's Bash tool runs, with no extra install.

07Sources

Updated 2026-10-31