> ## Documentation Index
> Fetch the complete documentation index at: https://microsanbox-staging-toks-cloud-snapshot-contracts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> What sandboxes are and how to configure them
A sandbox is a microVM with its own Linux kernel, filesystem, and network stack. Your application or the `msb` CLI starts it as a child process on your machine or on [microsandbox cloud](/cloud/overview), then talks to the guest agent to run commands, move files, and control lifecycle.
The security boundary is hardware virtualization, not Linux namespaces. That makes sandboxes a good fit for untrusted workloads: user-submitted code, AI agent actions, plugins, dependency installs, CI jobs, scrapers, and tools that should not inherit the host process's full privileges.
## Create a sandbox
At minimum, a sandbox needs a name and an image. Everything else has defaults: 1 vCPU, 512 MiB memory, public-only networking, and `/bin/sh` as the default shell.
```rust Rust theme={null}
let sb = Sandbox::builder("worker")
.image("python")
.create()
.await?;
```
```typescript TypeScript theme={null}
await using sb = await Sandbox.builder("worker")
.image("python")
.create();
```
```python Python theme={null}
sb = await Sandbox.create("worker", image="python")
```
```go Go theme={null}
sb, err := m.CreateSandbox(ctx, "worker", m.WithImage("python"))
```
```bash CLI theme={null}
msb create python --name worker
```
Sandbox names must be non-empty and no longer than 128 UTF-8 bytes.
## Common configuration
Limited on cloud
```rust Rust theme={null}
let sb = Sandbox::builder("worker")
.image("python")
.memory(1024)
.cpus(2)
.env("DEBUG", "true")
.label("user.id", "alice")
.volume("/tmp/scratch", |v| v.tmpfs().size(100))
.create()
.await?;
```
```typescript TypeScript theme={null}
await using sb = await Sandbox.builder("worker")
.image("python")
.memory(1024)
.cpus(2)
.env("DEBUG", "true")
.label("user.id", "alice")
.volume("/tmp/scratch", (m) => m.tmpfs().size(100))
.create();
```
```python Python theme={null}
sb = await Sandbox.create(
"worker",
image="python",
memory=1024,
cpus=2,
env={"DEBUG": "true"},
labels={"user.id": "alice"},
volumes={"/tmp/scratch": Volume.tmpfs(size_mib=100)},
)
```
```go Go theme={null}
sb, err := m.CreateSandbox(ctx, "worker",
m.WithImage("python"),
m.WithMemory(1024),
m.WithCPUs(2),
m.WithEnv(map[string]string{"DEBUG": "true"}),
m.WithLabels(map[string]string{"user.id": "alice"}),
m.WithMounts(map[string]m.MountConfig{
"/tmp/scratch": m.Mount.Tmpfs(m.TmpfsOptions{SizeMiB: 100}),
}),
)
```
```bash CLI theme={null}
msb create python --name worker \
-c 2 \
-m 1G \
-e DEBUG=true \
--label user.id=alice \
--tmpfs /tmp/scratch:100
```
| Option | Default | Description |
| ------------ | ---------------- | --------------------------------------------------- |
| `image` | required | OCI image, local rootfs path, or disk image |
| `cpus` | `1` | Virtual CPU limit |
| `max_cpus` | same as `cpus` | Boot-time maximum possible virtual CPUs |
| `memory` | `512` | Guest memory limit in MiB |
| `max_memory` | same as `memory` | Boot-time maximum hotpluggable memory in MiB |
| `thp` | `madvise` | Guest transparent huge-page policy selected at boot |
| `workdir` | image default | Default working directory for commands |
| `shell` | `/bin/sh` | Shell used by `shell()` calls |
| `env` | empty | Environment variables |
| `labels` | empty | Key/value metadata for metric attribution |
| `volumes` | empty | Bind, named, tmpfs, or disk-image mounts |
| `network` | public-only | Network policy and published ports |
| `scripts` | empty | Named scripts mounted at `/.msb/scripts/` |
`max_cpus` and `max_memory` reserve live resize headroom. They default to the
starting `cpus` and `memory` values, so set them higher when a sandbox may need
to grow later. See [Tuning](/sandboxes/tuning) for the full change
model.
Labels are arbitrary `key=value` metadata attached to a sandbox. They can be set
at create time or changed while the sandbox is running, and they also select
sandboxes in bulk. See [Labels](/sandboxes/labels) for naming guidance, bulk
actions, metric attribution, and OCI image labels.
`cpus` and `memory` are limits, not reservations. Guest memory is allocated as the VM touches pages.
## Image sources
Most sandboxes start from an OCI image:
```bash theme={null}
msb create python --name worker
```
Local-only
You can also use a host directory as the root filesystem:
```bash theme={null}
msb create ./my-rootfs --name worker
```
Or boot from a disk image:
```bash theme={null}
msb create ./alpine.qcow2 --name worker
```
OCI images use a copy-on-write overlay so sandboxes can share cached base layers. Disk images are attached as block devices, so each sandbox should use its own disk image copy unless the image format handles its own snapshotting.
See [Images](/images/overview) and [Disk Images](/images/disk-images) for the full image model.
## Naming conflicts
Local-only
Creating a sandbox fails if another sandbox already has the same name. Use [`connect_or_create`](/sandboxes/lifecycle#converge-on-a-named-sandbox) when you want to reuse the current persisted identity and its configuration. Use replace when you explicitly want a fresh sandbox with that name:
```rust Rust theme={null}
let sb = Sandbox::builder("worker")
.image("python")
.replace()
.create()
.await?;
```
```typescript TypeScript theme={null}
await using sb = await Sandbox.builder("worker")
.image("python")
.replace()
.create();
```
```python Python theme={null}
sb = await Sandbox.create("worker", image="python", replace=True)
```
```go Go theme={null}
sb, err := m.CreateSandbox(ctx, "worker",
m.WithImage("python"),
m.WithReplace(),
)
```
```ruby Ruby theme={null}
sb = Microsandbox::Sandbox.create("worker", image: "python", replace: true)
```
```bash CLI theme={null}
msb create --replace python --name worker
```
When replacing a running sandbox, microsandbox attempts graceful shutdown before force-killing it. Use `replace_with_timeout` or `--replace-with-timeout` when the workload needs a longer grace period.
## Where to go next
* [Lifecycle](/sandboxes/lifecycle): start, stop, detach, wait, and remove sandboxes
* [Tuning](/sandboxes/tuning): change settings after create
* [Labels](/sandboxes/labels): organize, select, and attribute sandboxes
* [Secrets](/sandboxes/secrets): inject credentials without exposing values
* [Bootstrap](/sandboxes/bootstrap): prepare scripts, patches, and PID 1
* [Commands](/sandboxes/commands): run commands and stream output
* [Volumes](/sandboxes/volumes): persist or share data
* [Networking](/networking/overview): control egress, ingress, DNS, and ports
* [SDK reference](/sdk/overview): per-language API details