Skip to main content
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: 
let sb = Sandbox::builder("worker")
    .image("python")
    .label("app", "engine")
    .label("user.id", "alice")
    .create()
    .await?;
The OCI image’s own labels (LABEL instructions, org.opencontainers.image.*, etc.) are imported automatically at create time. A label you set yourself overrides the image’s value on a key collision. Image labels using a reserved prefix are skipped.

​
Change while running

Add, change, or remove labels without recreating the sandbox: 
sb.modify().label("tier", "web").remove_label("stale").apply().await?;

​
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
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. If 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.