Can Microsandbox Run Untrusted Code? Security Model and SDK Examples

Yes—Microsandbox is explicitly architected to execute untrusted code inside hardware-isolated micro-VMs, with the guest kernel, filesystem, and network completely separated from the host.

Microsandbox (superradcompany/microsandbox) is an open-source sandboxing engine that provides hardware-level isolation for arbitrary workloads. Unlike container-based solutions that share the host kernel, Microsandbox launches each workload in its own Linux micro-VM using KVM (Linux) or Hypervisor.framework (macOS). This design makes it purpose-built for running untrusted code safely—whether that's user-submitted scripts, AI-generated code, third-party plugins, or CI jobs from unknown sources.

How Microsandbox Isolates Untrusted Code

The security model documented in docs/security/overview.mdx establishes a strict trusted boundary between host and guest. The guest is treated as completely untrusted, while the host-side VMM mediates all interactions.

Core Isolation Layers

Component	Protection Mechanism
Micro-VM (KVM/Hypervisor.framework)	Hardware-level virtualization isolates the guest kernel from host memory and syscalls
Virtio device mediation	All guest I/O passes through host-controlled virtio channels; no direct hardware access
Filesystem broker	Exposes only the VM image and explicit bind-mounts; host filesystem remains invisible
Egress-only networking	Guest can reach public internet but cannot access host, loopback, link-local, or cloud metadata networks
Host-side secret injection	Credentials bind as placeholders in-guest; real secrets never enter the VM
In-guest root isolation	Workload runs as root inside VM without host privileges (droppable via configuration)

These layers ensure that untrusted code cannot escape the sandbox through kernel exploits, filesystem traversal, network reconnaissance, or secret exfiltration.

Implementation in Source Files

The isolation is enforced by specific components in the codebase:

• crates/runtime/lib/control.rs — Host-side control loop that mediates all guest requests for network, filesystem, and secret operations
• crates/agentd/src/main.rs — In-guest agent that receives commands; the only trusted code visible inside the micro-VM
• crates/network/lib/secrets/handler.rs — Keeps real secrets on host, injecting only bound placeholders into guest
• crates/filesystem/lib/backends/passthroughfs/unix/mod.rs — Path containment for bind-mounts preventing directory escapes
• sdk/rust/lib/config/mod.rs — Configuration structures for network policies, mount restrictions, and hardening knobs

Running Untrusted Code: SDK Examples

Microsandbox provides idiomatic SDKs for Rust, Python, TypeScript, and Go. Each follows the same pattern: create an isolated environment, execute arbitrary code, and capture output—without exposing the host.

Rust SDK (Native)

use microsandbox::Sandbox;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create sandbox with explicit resource limits
    let sandbox = Sandbox::builder("untrusted-demo")
        .image("python")
        .cpus(1)
        .memory(512)
        .create()
        .await?;

    // Execute untrusted Python code
    let output = sandbox
        .exec("python", ["-c", "import secrets; print(secrets.token_hex(8))"])
        .await?;

    println!("Random token from untrusted code: {}", output.stdout()?);
    sandbox.stop().await?;
    Ok(())
}

The Sandbox::builder() API in sdk/rust/lib/config/mod.rs defines resource boundaries that constrain untrusted execution.

Python SDK

import asyncio
from microsandbox import Sandbox

async def main():
    sandbox = await Sandbox.create(
        "untrusted-demo",
        image="python",
        cpus=1,
        memory=512,
    )
    # Run untrusted code generating a UUID

    out = await sandbox.exec("python", ["-c", "import uuid; print(uuid.uuid4())"])
    print("UUID from untrusted sandbox:", out.stdout_text)
    await sandbox.stop()

asyncio.run(main())

TypeScript SDK

import { Sandbox } from "microsandbox";

await using sandbox = await Sandbox.builder("untrusted-demo")
    .image("python")
    .cpus(1)
    .memory(512)
    .create();

const out = await sandbox.exec("python", ["-c", "console.log('Hello from untrusted!')"]);
console.log(out.stdout());

The using declaration ensures deterministic cleanup of the isolated environment.

Go SDK

package main

import (
    "context"
    "fmt"
    "log"

    microsandbox "github.com/superradcompany/microsandbox/sdk/go"
)

func main() {
    ctx := context.Background()
    if err := microsandbox.EnsureInstalled(ctx); err != nil {
        log.Fatal(err)
    }

    sandbox, err := microsandbox.CreateSandbox(ctx, "untrusted-demo",
        microsandbox.WithImage("python"),
        microsandbox.WithCPUs(1),
        microsandbox.WithMemory(512),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer sandbox.Stop(ctx)

    out, err := sandbox.Exec(ctx, "python", []string{"-c", "print('untrusted Go exec')"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(out.Stdout())
}

CLI Quick-Start

npx microsandbox run python -- python -c "print('Hello from untrusted CLI')"

Security Responsibilities When Running Untrusted Code

Microsandbox provides strong isolation primitives, but secure deployment requires attention to three areas:

1. Host security posture — Keep the VMM and hypervisor patched; the host remains a trusted computing base
2. Image provenance — Verify or build the VM images you execute; malicious images can behave badly even within isolation boundaries
3. Network policy configuration — The default deny-by-default for private ranges is protective, but customize egress rules via sdk/rust/lib/config/mod.rs for your threat model

Summary

• Microsandbox is designed for untrusted code execution via hardware-virtualized micro-VMs, not container-level isolation
• The guest kernel is completely untrusted and cannot access host syscalls, memory, or filesystem directly
• All SDKs (Rust, Python, TypeScript, Go) and the CLI provide uniform APIs for spawning isolated workloads
• Critical enforcement happens in crates/runtime/lib/control.rs (host mediation), crates/agentd/src/main.rs (in-guest command proxy), and crates/network/lib/secrets/handler.rs (secret protection)
• Operators must still manage host hardening, image trust, and network policies to complete the security model

Frequently Asked Questions

Is Microsandbox safer than Docker for running untrusted code?

Yes, due to architectural differences. Docker containers share the host kernel, so a kernel vulnerability in the container can compromise the host. Microsandbox uses hardware virtualization (KVM/Hypervisor.framework) with a separate guest kernel, eliminating this attack surface. Even complete guest kernel compromise cannot directly access host resources.

Can untrusted code escape through the network?

No, by default. The network layer in crates/network/ implements egress-only connectivity with deny-by-default for private IP ranges (loopback, link-local, cloud metadata). The guest can reach public internet endpoints you allow, but cannot probe the host or internal infrastructure.

What happens if I need to give untrusted code access to sensitive data?

Use secret binding instead of embedding credentials. As implemented in crates/network/lib/secrets/handler.rs, secrets remain on the host and are only sent to explicitly allowed destinations. The guest sees placeholder values and cannot exfiltrate the actual credentials even if fully compromised.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}