Microsandbox

I wasn’t very happy with my current sandboxing solution (E2B), so decided to give a try to MicroSandbox, and was glad I switched.

What are sandboxes for?

We’re entering an era where AI agents don’t just suggest code, they write it and execute it. They also install packages, run scripts, inspect files, call CLIs, start dev servers, and sometimes touch code we barely understand yet.

That changes the infrastructure we need around development.

If an agent is going to run arbitrary commands, it needs a safe place to do it. Not my laptop. Not my production machine. Not a long-lived environment full of secrets. It needs a disposable, isolated computer where mistakes are contained and experiments are cheap.

That’s what sandboxes are for.

A good sandbox gives each agent its own environment: a filesystem, a shell, network boundaries, resource limits, and a way to run and inspect code without trusting it too much. For AI coding tools, this is becoming table stakes.

The Microsandbox CLI

Before using the Microsandbox SDK, it’s worth getting familiar with what Microsandbox can do through the Microsandbox CLI.

In this post we’ll look into how to:

• Install the msb CLI.
• Create a persistent Node-based sandbox.
• Execute shell commands inside the sandbox.
• Install runtime tools and project dependencies.
• Create and run an Astro app inside the sandbox.
• Expose the Astro dev server through a mapped local port.
• Inspect, stop, restart, and remove the sandbox.

Installation

We can install the CLI globally, by downloading and running the following script:

curl -fsSL https://install.microsandbox.dev | sh

After the installation, you’ll have to source ~/.zshrc, then verify the installation:

msb --version
msb 0.4.6

Using the msb CLI

In this section we’ll demo how to create a sandbox named astro-demo, which is nothing but a cointainerized Astro app, running in a Microsandbox.

1. Create A Persistent Node Sandbox

Let’s use the msb CLI to create a named sandbox from the node:22.22.3-slim Docker image and publish Astro’s default dev port:

msb run \
  --name astro-demo \
  --detach \
  --replace \
  -m 2G \
  -c 2 \
  -p 4324:4321 \
  node:22.22.3-slim

Several things going on in the command above:

• The --name flag will name our persistent sandbox as astro-demo.
• The --detach flag to run the sandbox in the background and returns the terminal inmediately.
• The --replace flag will recreate the sandbox if it already exists.
• The -m 2G flag sets 2GB of memory.
• The -c 2 flag sets 2 virtual CPUs.
• The -p 4324:4321 is mapping ports from host 4324 -> sandbox 4321.
• We’re using the node:22.22.3-slim Docker image, which gives us Node.js preinstalled, based on Debian slim. The slim variant is smaller than the full Node image, but still supports apt-get, so we can install tools like git and curl.

2. Prepare The Runtime

Now that our sandbox is running, we can install tools into it:

msb exec astro-demo -- sh -c "apt-get update && apt-get install -y git curl"

Enable pnpm as our package manager:

msb exec astro-demo -- corepack enable
msb exec astro-demo -- corepack prepare pnpm@latest --activate

Verify that everything was successfully installed by checking their versions:

msb exec astro-demo -- node --version
msb exec astro-demo -- pnpm --version
msb exec astro-demo -- git --version

3. Create An Astro App

Let’s create the app inside /home/workspace:

msb exec astro-demo -- sh -c "mkdir -p /home/workspace && cd /home/workspace && pnpm create astro@latest . --template basics --no-install --yes"

The command above will create without installing dependencies. Let’s install them:

msb exec astro-demo -- sh -c "cd /home/workspace && pnpm install --dangerously-allow-all-builds"

pnpm install --dangerously-allow-all-builds

If pnpm create astro prompts unexpectedly, use npm instead:

msb exec astro-demo -- sh -c "mkdir -p /home/workspace && cd /home/workspace && npm create astro@latest . -- --template basics --install --yes"

4. Start The Astro Dev Server

Ok, let’s start the Astro dev server on all interfaces so the published port can reach it:

msb exec astro-demo -- sh -c "cd /home/workspace && pnpm dev --host 0.0.0.0 --port 4321"

The command above also starts the sandbox if it was stopped. Now the sandboxed app should be available at https://localhost:4324 👍

msb stop astro-demo # Stop
msb start astro-demo # Start

Then inspect the logs:

msb logs astro-demo

nohup msb exec astro-demo -- sh -c "cd /home/workspace && pnpm dev --host 0.0.0.0 --port 4321" </dev/null >/dev/null 2>&1 &
disown

ps aux | grep "msb exec astro-demo"

kill <PID>

5. Run Commands Inside The Sandbox

Using msb we can inspect files within the sandbox:

msb exec astro-demo -- sh -c "cd /home/workspace && ls -la"

Read package metadata:

msb exec astro-demo -- sh -c "cd /home/workspace && cat package.json"

Run a build:

msb exec astro-demo -- sh -c "cd /home/workspace && pnpm build"

6. Test Environment Variables

Run a one-off command with an env var:

msb exec astro-demo -- sh -c "DEMO_ENV=hello node -e 'console.log(process.env.DEMO_ENV)'"

For app runtime env vars, start the dev server with env in the shell command:

msb exec astro-demo -- sh -c "cd /home/workspace && PUBLIC_DEMO_VALUE=hello pnpm dev --host 0.0.0.0 > /tmp/astro.log 2>&1 &"

7. Inspect Sandbox State

The msb CLI offers a bunch of commands for managing sandboxes. We can list them:

msb ls

Show the ones that are running:

msb ps

Inspect a particular sandbox:

msb inspect astro-demo

Show its metrics:

msb metrics astro-demo

Show its logs:

msb logs astro-demo

8. Stop And Resume

To start (or restart) an existing sandbox:

msb start astro-demo

To stop it:

msb stop astro-demo

9. Clean Up

Whenever we are done with a sandbox, we can stop it:

msb stop astro-demo

And remove it:

msb rm astro-demo

Huzzah!

We’ve played a bit with the CLI, now go have fun with the SDK.