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'
  }
});

Label validation remains owned by the underlying Cloudflare Containers runtime, keeping Sandbox aligned with the platform label contract.

You can verify the behavior locally by calling getSandbox() with labels and confirming the container starts as normal. In local development the applied labels are visible on the underlying container through docker inspect.

Unit tests cover option forwarding, cache deduplication for repeated label configurations, order-independent label comparison, clearing labels with an empty object, Durable Object persistence/restoration, and clone behavior so caller-side mutation does not affect stored labels.

The package README and the SandboxOptions type documentation now describe the labels option and its start-time behavior.

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 8fa7584

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: 8fa7584

[github-actions]

🐳 Docker Images Published

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

Usage:

FROM cloudflare/sandbox:0.0.0-pr-798-8fa75840

Version: 0.0.0-pr-798-8fa75840

---

📦 Standalone Binary

For arbitrary Dockerfiles:

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

Download via GitHub CLI:

gh run download 28597333793 -n sandbox-binary

Extract from Docker:

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

[ghostwriternr]

fixed some of the language around validation from the PR desc, rest looks great 🙌