microsandbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

microsandbox

microsandbox creates hardware-isolated microVMs that boot in under 100ms. Each sandbox is a real VM with its own Linux kernel — not a container.

microsandbox 创建硬件隔离的microVM，启动时间不到100毫秒。每个沙箱都是拥有独立Linux内核的真实VM，而非容器。

Setup

安装配置

Check if microsandbox is installed:

bash

msb --version

If not installed, run the setup script:

bash

bash scripts/setup.sh

This installs

msb

~/.microsandbox/bin/

and

libkrunfw

~/.microsandbox/lib/

检查microsandbox是否已安装：

bash

msb --version

若未安装，运行安装脚本：

bash

bash scripts/setup.sh

该脚本会将

msb

安装到

~/.microsandbox/bin/

，将

libkrunfw

安装到

~/.microsandbox/lib/

。

Quick reference

快速参考

Run a one-off command in a sandbox

在沙箱中运行一次性命令

bash

msb run <image> [options] -- <command>

Examples:

bash

msb run python:3.12 -- python -c "print('hello from sandbox')"
msb run -m 1G node:22 -- node -e "console.log(process.version)"
msb run alpine:latest -- sh -c "uname -a && cat /etc/os-release"

bash

msb run <image> [options] -- <command>

示例：

bash

msb run python:3.12 -- python -c "print('hello from sandbox')"
msb run -m 1G node:22 -- node -e "console.log(process.version)"
msb run alpine:latest -- sh -c "uname -a && cat /etc/os-release"

Create a persistent sandbox

创建持久化沙箱

bash

msb create --name <name> [options] <image>
msb exec <name> -- <command>
msb shell <name>
msb stop <name>
msb start <name>                  # Resume a stopped sandbox
msb rm <name>

Example workflow:

bash

undefined

bash

msb create --name <name> [options] <image>
msb exec <name> -- <command>
msb shell <name>
msb stop <name>
msb start <name>                  # 恢复已停止的沙箱
msb rm <name>

示例工作流：

bash

undefined

Create a Python development sandbox

创建Python开发沙箱

msb create --name dev -m 1G -c 2 python:3.12

Install packages

安装依赖包

msb exec dev -- pip install requests numpy

Run code

运行代码

msb exec dev -- python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"

Interactive shell

交互式Shell

msb shell dev

Stop and resume later

停止沙箱，后续可恢复

msb stop dev msb start dev

Clean up

清理沙箱

msb stop dev msb rm dev

undefined

msb stop dev msb rm dev

undefined

Common options

常用选项

Flag	Description	Example
`-n, --name`	Name the sandbox	`--name my-sandbox`
`-m, --memory`	Memory allocation	`-m 512M` , `-m 1G`
`-c, --cpus`	Number of vCPUs	`-c 2`
`-v, --volume`	Mount volume	`-v /host/path:/guest/path`
`-p, --port`	Publish port	`-p 8080:80` , `-p 5353:5353/udp`
`-e, --env`	Set env variable	`-e API_KEY=xxx`
`-w, --workdir`	Working directory	`-w /app`
`-d, --detach`	Run in background (run only)	`-d`
`-u, --user`	Run as user	`-u nobody`
`-H, --hostname`	Set guest hostname	`-H myhost`
`--shell`	Default shell program	`--shell /bin/bash`
`--replace`	Replace existing sandbox	`--replace`
`--entrypoint`	Override entrypoint	`--entrypoint /bin/sh`
`--pull`	Pull policy	`--pull always`
`--max-duration`	Auto-stop timeout	`--max-duration 5m`
`--idle-timeout`	Idle auto-stop	`--idle-timeout 30s`
`--tmpfs`	Mount tmpfs	`--tmpfs /tmp:100M`
`--script`	Inject script	`--script setup:./setup.sh`

参数	描述	示例
`-n, --name`	为沙箱命名	`--name my-sandbox`
`-m, --memory`	内存分配	`-m 512M` , `-m 1G`
`-c, --cpus`	vCPU数量	`-c 2`
`-v, --volume`	挂载卷	`-v /host/path:/guest/path`
`-p, --port`	发布端口	`-p 8080:80` , `-p 5353:5353/udp`
`-e, --env`	设置环境变量	`-e API_KEY=xxx`
`-w, --workdir`	工作目录	`-w /app`
`-d, --detach`	后台运行（仅适用于run命令）	`-d`
`-u, --user`	指定运行用户	`-u nobody`
`-H, --hostname`	设置沙箱主机名	`-H myhost`
`--shell`	默认Shell程序	`--shell /bin/bash`
`--replace`	替换已存在的沙箱	`--replace`
`--entrypoint`	覆盖镜像入口点	`--entrypoint /bin/sh`
`--pull`	镜像拉取策略	`--pull always`
`--max-duration`	自动停止超时时间	`--max-duration 5m`
`--idle-timeout`	空闲自动停止超时	`--idle-timeout 30s`
`--tmpfs`	挂载tmpfs	`--tmpfs /tmp:100M`
`--script`	注入脚本	`--script setup:./setup.sh`

Manage sandboxes

管理沙箱

bash

msb ls                    # List all sandboxes
msb ls --running          # Running only
msb ps                    # Show running sandboxes with status
msb ps -a                 # All sandboxes including stopped
msb inspect <name>        # Detailed sandbox info
msb metrics <name>        # Live CPU/memory/IO stats
msb stop <name>           # Graceful shutdown
msb stop --force <name>   # Force kill
msb stop -t 10 <name>    # Wait 10s then force kill
msb rm <name>             # Remove stopped sandbox
msb rm --force <name>     # Stop and remove in one step

bash

msb ls                    # 列出所有沙箱
msb ls --running          # 仅列出运行中的沙箱
msb ps                    # 显示运行中沙箱的状态
msb ps -a                 # 列出所有沙箱（包括已停止的）
msb inspect <name>        # 查看沙箱详细信息
msb metrics <name>        # 查看实时CPU/内存/IO统计
msb stop <name>           # 优雅关闭沙箱
msb stop --force <name>   # 强制终止沙箱
msb stop -t 10 <name>    # 等待10秒后强制终止
msb rm <name>             # 删除已停止的沙箱
msb rm --force <name>     # 一步完成停止并删除沙箱

Manage images

管理镜像

bash

msb pull <image>          # Pre-cache an OCI image
msb images                # List cached images (alias: msb image ls)
msb image inspect <img>   # Image metadata
msb rmi <image>           # Remove cached image (alias: msb image rm)

bash

msb pull <image>          # 预缓存OCI镜像
msb images                # 列出已缓存的镜像（别名：msb image ls）
msb image inspect <img>   # 查看镜像元数据
msb rmi <image>           # 删除已缓存的镜像（别名：msb image rm）

Manage volumes

管理卷

bash

msb volume create <name>          # Create named volume
msb volume create <name> --size 5G  # With quota
msb volume ls                     # List volumes
msb volume inspect <name>         # Volume details
msb volume rm <name>              # Remove volume

bash

msb volume create <name>          # 创建命名卷
msb volume create <name> --size 5G  # 创建带配额的命名卷
msb volume ls                     # 列出所有卷
msb volume inspect <name>         # 查看卷详细信息
msb volume rm <name>              # 删除卷

Volume mounts

卷挂载

bash

undefined

bash

undefined

Bind mount host directory

绑定挂载主机目录

msb run -v ./project:/app python:3.12 -- python /app/script.py

Named volume (persistent across sandboxes)

命名卷（可在多个沙箱间持久化）

msb volume create mydata msb run -v mydata:/data alpine -- sh -c "echo 'test' > /data/file.txt" msb run -v mydata:/data alpine -- cat /data/file.txt

undefined

msb volume create mydata msb run -v mydata:/data alpine -- sh -c "echo 'test' > /data/file.txt" msb run -v mydata:/data alpine -- cat /data/file.txt

undefined

Networking and security

网络与安全

bash

undefined

bash

undefined

No network access

禁用网络访问

msb run --no-network python:3.12 -- python script.py

Block specific domains

阻止特定域名

msb run --dns-block-domain "ads.example.com" python:3.12

Inject secrets (placeholder substitution — real value never enters VM)

注入密钥（占位符替换——真实值永远不会进入VM）

msb run --secret "OPENAI_API_KEY=sk-xxx@api.openai.com" python:3.12

TLS interception for secret injection

通过TLS拦截注入密钥

msb run --tls-intercept --secret "API_KEY=xxx@api.example.com" python:3.12

Limit connections

限制连接数

msb run --max-connections 10 python:3.12

undefined

msb run --max-connections 10 python:3.12

undefined

Registry authentication

镜像仓库认证

bash

msb registry login ghcr.io --username octocat
msb registry logout ghcr.io
msb registry ls

bash

msb registry login ghcr.io --username octocat
msb registry logout ghcr.io
msb registry ls

Install sandbox as command

将沙箱安装为系统命令

bash

msb install python:3.12          # Install as 'python' command
msb install --name py python:3.12  # Custom name
msb install --list               # Show installed commands
msb uninstall py                 # Remove

bash

msb install python:3.12          # 将沙箱安装为'python'命令
msb install --name py python:3.12  # 自定义命令名称
msb install --list               # 查看已安装的命令
msb uninstall py                 # 卸载命令

Key behaviors

核心特性

Sandboxes are real microVMs with hardware-level isolation (hypervisor boundary)
Boot time is under 100ms
Default network policy is public-only (blocks private ranges, metadata endpoints)
Sandboxes from
```
msb run
```
without
```
--name
```
are ephemeral (destroyed after exit)
Sandboxes from
```
msb create
```
or
```
msb run --name
```
are persistent (survive until
```
msb rm
```
)
```
msb create
```
always runs in background; use
```
msb run -d
```
for detached one-off runs
Secrets use placeholder substitution — real credentials never enter the VM
Use
```
--replace
```
to recreate an existing sandbox with new settings

沙箱是真实的microVM，具备硬件级隔离（基于虚拟机管理程序边界）
启动时间不到100毫秒
默认网络策略为仅允许公网访问（阻止私有网段、元数据端点）
未使用
```
--name
```
参数的
```
msb run
```
创建的沙箱是临时沙箱（退出后自动销毁）
使用
```
msb create
```
或
```
msb run --name
```
创建的沙箱是持久化沙箱（直到执行
```
msb rm
```
才会销毁）
```
msb create
```
始终在后台运行；如需后台运行一次性命令，使用
```
msb run -d
```
密钥采用占位符替换机制——真实凭证永远不会进入VM
使用
```
--replace
```
参数可根据新配置重新创建已存在的沙箱

Troubleshooting

故障排查

msb

is not found after installation:

bash

source ~/.bashrc   # or ~/.zshrc

Check installation:

bash

ls ~/.microsandbox/bin/msb
ls ~/.microsandbox/lib/libkrunfw*

For full CLI reference, see references/cli-reference.md. For SDK usage, see references/sdk-typescript.md and references/sdk-rust.md.

若安装后找不到

msb

命令：

bash

source ~/.bashrc   # 或 ~/.zshrc

检查安装情况：

bash

ls ~/.microsandbox/bin/msb
ls ~/.microsandbox/lib/libkrunfw*

完整CLI参考请查看 references/cli-reference.md。 SDK使用说明请查看 references/sdk-typescript.md 和 references/sdk-rust.md。