Add sandbox container labels option

[aron-cf]

Fixes #790
Container instances created through the Sandbox SDK could not be tagged with custom metadata. The underlying Cloudflare Containers platform supports key-value labels that flow into the analytics pipeline, where they can be used to filter and group usage metrics by dimensions such as tenant, environment, or workload. The SDK exposed sleep and transport options through SandboxOptions but offered no way to set labels, so callers had no first-class path to attribute container usage back to their own entities. This addresses the request in #790.

This change adds a labels field to SandboxOptions, letting callers attach labels at the same call site they already use to configure a sandbox. Labels are stored on the sandbox and applied when the container next starts, which keeps them consistent with how the platform consumes them. Changing labels while a container is already running is allowed, but the new values only take effect on the following start.

const sandbox = getSandbox(env.Sandbox, 'tenant-workspace', {
  sleepAfter: '30m',
  labels: {
    tenantId: 'tenant_123',
    workload: 'code_workspace'
  }
});

The platform validates label names when the container starts and rejects anything that is not a non-empty string of letters, digits, and underscores, along with control characters in label values. On its own, that means a typo such as a hyphen in a label name would only fail later, at the first operation that starts the container, far from where the label was supplied. To close that gap, labels are now validated synchronously inside getSandbox() so a bad label throws immediately at the call site with a clear message.

// Throws: Label name "tenant-id" is invalid: only letters, digits,
// and underscores ([A-Za-z0-9_]) are allowed
getSandbox(env.Sandbox, 'tenant-workspace', {
  labels: { 'tenant-id': 'tenant_123' }
});

You can verify the behavior locally by calling getSandbox() with a valid set of labels and confirming the container starts as normal, then repeating the call with a label name that contains a hyphen or other disallowed character and observing that it throws before any container work happens. In local development the applied labels are visible on the underlying container through docker inspect.

The validation rules are covered by unit tests in the SDK that assert invalid names, empty names, and control characters in values are rejected, and that valid names pass through untouched. The existing label configuration and caching tests continue to pass.

The package README and the SandboxOptions type documentation now describe the labels option and its constraints so the naming rules are discoverable without reaching for the platform documentation.

---

[changeset-bot]

🦋 Changeset detected

Latest commit: fe40abd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/sandbox	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

Devin Review found 1 potential issue.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@cloudflare/sandbox@798

commit: fe40abd

[github-actions]

🐳 Docker Images Published

Variant	Image
Default	cloudflare/sandbox:0.0.0-pr-798-fe40abdc
Python	cloudflare/sandbox:0.0.0-pr-798-fe40abdc-python
OpenCode	cloudflare/sandbox:0.0.0-pr-798-fe40abdc-opencode
Musl	cloudflare/sandbox:0.0.0-pr-798-fe40abdc-musl

Usage:

FROM cloudflare/sandbox:0.0.0-pr-798-fe40abdc

Version: 0.0.0-pr-798-fe40abdc

---

📦 Standalone Binary

For arbitrary Dockerfiles:

COPY --from=cloudflare/sandbox:0.0.0-pr-798-fe40abdc /container-server/sandbox /sandbox
ENTRYPOINT ["/sandbox"]

Download via GitHub CLI:

gh run download 28510547234 -n sandbox-binary

Extract from Docker:

docker run --rm cloudflare/sandbox:0.0.0-pr-798-fe40abdc cat /container-server/sandbox > sandbox && chmod +x sandbox