How Microsandbox Handles Third-Party Scripts: Secure Execution in Isolated VMs

Microsandbox executes third-party scripts inside isolated guest VMs via the Sandbox::shell() API, with filesystem overlays, network policies, and secret injection enforcing strict security boundaries.

Microsandbox treats third-party scripts as untrusted shell commands that run inside lightweight, fully isolated virtual machines. The Rust SDK exposes a simple shell() method on the Sandbox struct, while the underlying exec protocol and security profiles guarantee that external code cannot access the host system or unauthorized resources. This article breaks down the exact mechanisms the superradcompany/microsandbox source code uses to safely run arbitrary scripts.

Sandbox Creation and the Shell API

Microsandbox exposes a high-level Rust API that turns sandbox configuration into a secure execution environment.

Building the Sandbox

In sdk/rust/lib/sandbox/mod.rs, the Sandbox::builder function initializes the guest VM with an overlay filesystem, a network namespace, and a security profile. The builder pattern lets callers chain policies before calling .build().await.

Executing Third-Party Scripts

Once the sandbox is live, the host calls sandbox.shell(<command>)—also defined in sdk/rust/lib/sandbox/mod.rs around lines 1146–1147—to send a shell command into the guest. This method returns an ExecOutput struct that captures stdout, stderr, and the exit status of the script.

The Exec Protocol Behind Script Execution

Commands do not run directly on the host. Instead, the host communicates with the guest through a dedicated exec protocol.

Protocol Definition

The file crates/protocol/lib/exec.rs defines the request and response messages for exec sessions. When the host invokes shell(), it serializes an exec request and transmits it to the microsandbox agent.

Guest-Side Process Spawning

Inside the VM, the agent daemon (crates/agentd) receives the request and spawns the command inside the guest’s init namespace. It attaches to the process standard I/O and streams output back to the host. Exit codes, signals, and errors propagate to the caller, so the host receives the same observable behavior it would from a local subprocess—without the local risk.

Filesystem and Network Isolation Layers

Isolation is enforced through layered policies that limit what a third-party script can see and reach.

Filesystem Isolation

The sandbox root is constructed from a read-only base image plus a writable overlay managed by crates/filesystem. Scripts see only the files present in the image and any files explicitly written into the overlay. The rootfs remains read-only except for the overlay layer, preventing persistent tampering with system files.

Network Policy Enforcement

The NetworkPolicy type controls egress traffic. Callers can use NetworkPolicy::allow_all() for open access or NetworkPolicy::allow_host("api.example.com") to restrict outbound connections to specific destinations. The test file sdk/rust/tests/tls.rs demonstrates sandbox creation with default or restricted networking, while sdk/rust/tests/security_profile.rs validates mount and isolation options by executing scripts and inspecting their output.

Secret Injection and Safety Guarantees

Beyond filesystem and network boundaries, Microsandbox protects sensitive data that scripts require at runtime.

Environment Secrets

Secrets are injected as environment variables when the sandbox launches. For example, sdk/rust/tests/net-secrets-body.rs shows a script running echo $API_KEY inside the guest. These values are only exposed inside the VM and are redacted from host logs, ensuring that third-party code can use credentials without leaking them to the host environment.

Capability Dropping and Read-Only Enforcement

The sandbox’s SecurityProfile drops privileged Linux capabilities, enforces the read-only rootfs, and limits network egress according to the policy. Because the command runs in a separate VM, a misbehaving or malicious script cannot escape to the host kernel or filesystem.

Practical Example: Securely Running External Scripts

The following Rust example demonstrates how to configure a sandbox and execute third-party commands safely:

use microsandbox::Sandbox;

// 1️⃣ Build a sandbox with a custom network policy and a secret.
let sb = Sandbox::builder("demo")
    .network_policy(NetworkPolicy::allow_host("api.example.com"))
    .secret("API_KEY", "super-secret-token")
    .build()
    .await
    .expect("failed to create sandbox");

// 2️⃣ Run a simple script that prints the secret.
let output = sb.shell("echo $API_KEY").await.expect("script failed");
println!("Script output: {}", output.stdout);

// 3️⃣ Run a more complex script, piped through a shell.
let multi = sb.shell("curl -s https://api.example.com/data | jq .field")
    .await
    .expect("curl failed");
println!("Result: {}", multi.stdout);

In this example, the external curl and jq binaries run entirely inside the guest VM. The script can reach only api.example.com, accesses the secret through the environment, and cannot write to the host filesystem.

Summary

• Microsandbox handles third-party scripts by executing them inside isolated guest VMs rather than on the host.
• The Sandbox::builder and sandbox.shell() APIs in sdk/rust/lib/sandbox/mod.rs provide the primary interface for running scripts.
• The exec protocol defined in crates/protocol/lib/exec.rs transports commands to the guest agent, which spawns processes and streams I/O back to the host.
• Filesystem isolation uses a read-only rootfs with a writable overlay layer, preventing host tampering.
• NetworkPolicy controls egress traffic, allowing fine-grained restrictions on what external hosts a script can reach.
• Secrets are injected at launch and remain confined to the VM, with redaction protecting host logs.

Frequently Asked Questions

How does Microsandbox prevent a third-party script from accessing the host filesystem?

Microsandbox constructs a sandbox root from a read-only image plus a writable overlay managed by crates/filesystem. The guest VM sees only its own filesystem tree, and the host root remains inaccessible because the script executes inside a separate kernel namespace according to the SecurityProfile.

What protocol transports script commands from the host to the guest VM?

The exec protocol, defined in crates/protocol/lib/exec.rs, carries exec requests from the host to the agent daemon (crates/agentd) running inside the guest. The agent spawns the script process in the guest init namespace and returns stdout, stderr, and exit codes to the host.

Can network access be restricted for specific third-party scripts?

Yes. The Rust SDK accepts a NetworkPolicy during sandbox construction. You can call NetworkPolicy::allow_host("hostname") to permit only specific destinations, or NetworkPolicy::allow_all() for broader access. Tests in sdk/rust/tests/tls.rs demonstrate both restricted and default networking configurations.

How are secrets protected when passed to scripts inside the sandbox?

Secrets are injected as environment variables at sandbox startup and are only visible inside the guest VM. As shown in sdk/rust/tests/net-secrets-body.rs, scripts reference them directly, but the values are redacted from host logs and never exposed to the host process space.

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