Labels

Labels are key=value pairs you attach to a sandbox to organize it. They let you act on many sandboxes at once with a single command, and break metrics down by whatever dimension you choose, such as user, tenant, or job.

Keys

Label keys cannot start with the reserved prefixes sandbox., microsandbox., or service.. Those namespaces belong to the runtime, which sets attributes under them itself and rejects any sandbox you try to create with a label key that uses one. Values may be empty. A valueless label such as --label gpu is stored as gpu="", matching Docker’s label semantics. Use empty values for marker labels, and use explicit values when you need filtering or metrics dimensions such as user.id=alice or tenant=acme.

Add at create time

Attach labels when you create a sandbox. Labels are repeatable, and a bare key with no value is allowed:

const sb = await Sandbox.builder("worker")
    .image("python")
    .label("app", "engine")
    .label("user.id", "alice")
    .create();

let sb = Sandbox::builder("worker")
    .image("python")
    .label("app", "engine")
    .label("user.id", "alice")
    .create()
    .await?;

sb = await Sandbox.create(
    "worker",
    image="python",
    labels={"app": "engine", "user.id": "alice"},
)

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithLabel("app", "engine"),
    m.WithLabel("user.id", "alice"),
)

msb create python --name worker \
  --label app=engine \
  --label user.id=alice

microsandbox imports the OCI image’s own labels (LABEL instructions, org.opencontainers.image.*, etc.) automatically at create time. A label you set yourself overrides the image’s value on a key collision. microsandbox skips image labels that use a reserved prefix.

Change while running

Add, change, or remove labels without recreating the sandbox:

await sandbox.modify({ labels: { tier: "web" }, labelsRemove: ["stale"] });

sb.modify().label("tier", "web").remove_label("stale").apply().await?;

await sb.modify(labels={"tier": "web"}, labels_rm=["stale"])

sb.Modify(ctx, m.ModifyOptions{
    Labels:       map[string]string{"tier": "web"},
    LabelsRemove: []string{"stale"},
})

msb modify worker --label tier=web --label-rm stale

Select in bulk

This is where labels earn their keep. Find every sandbox carrying a label, from the CLI or an SDK; pass more than one label to require all of them (AND-matched):

msb ps --label app=engine                    # matching sandboxes
msb ps --label app=engine --label tier=web   # only those with both

const page = await Sandbox.listWith((list) => list.label("app", "engine"));

let page = Sandbox::list_with(|list| list.label("app", "engine")).await?;

page = await Sandbox.list_with(labels={"app": "engine"})

page, err := m.ListSandboxesWith(ctx,
    m.WithListLabels(map[string]string{"app": "engine"}),
)

On the CLI, --label also drives the fleet commands directly, so you act on the whole group in one call instead of listing and looping:

msb stop --label app=engine        # stop every match
msb restart --label app=engine     # restart every match
msb rm --force --label app=engine  # remove every match

It works the same on ps, ls, start, stop, restart, ping, touch, and rm.

Attribute metrics

Labels flow into a sandbox’s metrics as dimensions, so you can break CPU, memory, and I/O down by any label you set, for example per user or per tenant. See Labels and per-user views for the PromQL detail. High-cardinality labels can increase the number of metric series your backend stores. Suppose an image label carries a commit SHA, build timestamp, or other noisy value. Run msb-metrics with --exclude-label-key <key> to drop that label from exported metrics while keeping it in the catalog. Use --no-labels to disable metric labels entirely.

Reference

For exact label and sandbox-selection APIs, see TypeScript, Rust, Python, or Go. For label-aware fleet commands, see Sandbox commands.

Getting Started

Sandboxes

Networking

Operations

Troubleshooting

Keys

Add at create time

Change while running

Select in bulk

Attribute metrics

Reference

​Keys

​Add at create time

​Change while running

​Select in bulk

​Attribute metrics

​Reference

Keys

Add at create time

Change while running

Select in bulk

Attribute metrics

Reference