Sandbox IDs

Every sandbox in OpenKruise Agents is addressed by a Sandbox ID. By default the ID is derived from the Kubernetes namespace and name of the underlying Sandbox CR; an optional short Sandbox ID can be enabled so that newly delivered sandboxes receive a short, stable identifier that fits comfortably into DNS-based E2B hostnames.

Short Sandbox IDs are available since v0.6.0. For how legacy IDs behave before and after enabling the feature, see Legacy ID Compatibility.

Legacy Sandbox IDs

Without any extra configuration, a sandbox is identified as:

<namespace>--<sandbox-name>

For example, a Sandbox named demo in namespace default has the ID default--demo.

This format is human-readable, but its length grows with both Kubernetes names. E2B native traffic embeds the Sandbox ID in a DNS name (https://<port>-<sandboxID>.<domain>), so a valid namespace and sandbox name can still produce an address that exceeds DNS label limits.

Short Sandbox IDs

When enabled, every successful Claim or Clone delivery assigns the sandbox a short ID in the form:

<operator-prefix><13-character suffix>

For example, with prefix prod-, a claimed sandbox may receive:

prod-aae57hpxaaqac

The 13-character suffix is generated by sandbox-manager and is always lowercase [a-z2-7]. The ID is persisted as a system-owned label on the Sandbox CR:

metadata:
  labels:
    agents.kruise.io/sandbox-id: aae57hpxaaqac

Key properties:

• One active ID per sandbox. A sandbox never carries both a legacy and a short ID at the same time. Once a short ID is assigned, it is the only ID for that delivery.
• Delivery-scoped stability. The ID identifies one user delivery, not the reusable Sandbox CR. Pause, resume, update, and Checkpoint operations within that delivery preserve the ID. When the sandbox is recycled back into the warm pool, the ID is retired.
• Clones get fresh IDs. Cloning from a sandbox or Checkpoint never inherits the source ID; each clone receives its own newly assigned ID.
• Opaque to clients. Sandbox IDs are exact-match values. Short IDs cannot be decoded back into a namespace and name; use the label-based lookup below instead.
• No background migration. Existing unlabeled sandboxes keep their legacy IDs. Labels are only written when a sandbox is successfully claimed or cloned.

Reserved label

agents.kruise.io/sandbox-id is owned by sandbox-manager:

• User-provided labels under the agents.kruise.io/ prefix are rejected by E2B-compatible requests, so no client can forge or overwrite the Sandbox ID.
• Pool and template materialization never copies the label into a new sandbox.
• Recycle clears the label when the current delivery ends.

Do not edit this label out of band; the supported protocol is the only writer.

Enabling Short Sandbox IDs

Short-ID assignment is disabled by default. It is controlled by two sandbox-manager startup flags:

Flag	Default	Description
--enable-short-sandbox-id	false	Assign short IDs to successfully claimed or cloned sandboxes
--short-sandbox-id-prefix	""	Prefix prepended verbatim to newly assigned short IDs

For example:

sandbox-manager --enable-short-sandbox-id=true --short-sandbox-id-prefix=prod- ...

No separator is inserted between the prefix and the suffix; if you want prod- as the visible prefix, include the hyphen in the configured value. The same prefix must be used on every sandbox-manager replica.

Prefix rules

A non-empty prefix:

• starts with a lowercase letter or digit;
• otherwise contains only lowercase letters, digits, and hyphens;
• must not contain the legacy ID separator --, keeping short and legacy ID spaces disjoint;
• is at most 50 characters, so prefix plus the 13-character suffix still fits the 63-character Kubernetes label-value limit.

Additional deployment constraints:

• With native E2B dynamic domains (<port>-<sandbox-id>.<domain>), keep the prefix at 44 characters or fewer so a five-digit port, separator, and ID still fit in one DNS label. The customized /kruise/* path is not subject to this limit.
• During a mixed-version rollout with older sandbox-manager replicas, keep the prefix at 37 characters or fewer.

The prefix is validated at startup even when assignment is disabled. Changing the prefix only affects future deliveries; existing labels are never regenerated.

Legacy ID Compatibility

Short IDs are an incremental feature: the legacy <namespace>--<name> format stays fully supported, and no background migration ever rewrites existing sandboxes.

ID resolution rule

Every component resolves a sandbox's current ID with exactly two branches:

Sandbox metadata	Resolved ID
Label agents.kruise.io/sandbox-id is non-empty	The label value, unchanged
The label is absent or empty	<namespace>--<name>

All lookup, routing, and authorization paths treat Sandbox IDs as opaque exact-match values. The server never reverse-parses a legacy ID to recover namespace and name; namespace/name diagnostics are only restored through the authorized channels described in Looking Up a Sandbox by ID.

Before enabling: assignment disabled

This is the default behavior, identical to versions without short-ID support:

• Every sandbox uses its legacy ID. Claim and Clone write no label.
• A recycled sandbox keeps its namespace/name, so every delivery of the same Sandbox CR is addressed by the same legacy ID again.
• Because the legacy ID uses -- as its separator, namespaces containing -- remain unsupported while legacy IDs are supported.

After enabling: assignment enabled

• Existing unlabeled sandboxes keep their legacy IDs. There is no background migration. Their legacy IDs remain fully valid for lookup, routing, and client connections until the sandbox is claimed or cloned again.
• Claim and Clone switch the ID atomically. When a sandbox is successfully claimed or cloned, a new short ID is assigned and the legacy ID stops resolving in the same step: requests that still use the old legacy ID receive not-found. One sandbox has exactly one active ID at any time; legacy and short IDs are never simultaneous aliases.
• Sandboxes created directly as Sandbox CRs (outside Claim/Clone) never receive a label and keep their legacy IDs indefinitely.
• Recycle clears the label. When a labeled sandbox returns to the warm pool, its short ID is retired and the sandbox is pooled unlabeled, resolving to its legacy ID again until the next delivery assigns a new short ID.

The enablement flag only controls which ID is written for a new delivery; it never changes how an active sandbox is read:

Assignment	Unlabeled pooled sandbox	Previously labeled pooled sandbox
Disabled	Uses its legacy ID	Prior ID is retired; the new delivery uses its legacy ID
Enabled	Receives a new short ID	Prior ID is replaced with a new short ID

Turning --enable-short-sandbox-id off is a safe way to stop new short-ID assignments, but it is not a data rollback:

• Active labeled sandboxes keep their short ID until the delivery ends.
• Recycle clears their labels before returning them to the pool.
• Later claims with assignment disabled use legacy IDs.

Because a legacy ID is derived from the reusable namespace/name, disabled mode does not provide a distinct ID for each reuse of the same Sandbox CR. If you rely on per-delivery uniqueness, keep assignment enabled once activated.

Behavior matrix

Scenario	Assignment disabled	Assignment enabled
ID of a new Claim / Clone	Legacy ID	Newly assigned short ID
Lookup by legacy ID for an unlabeled sandbox	Works	Works
Lookup by legacy ID for a labeled sandbox	N/A	Not found; use the short ID
Re-delivery of a recycled sandbox	Same legacy ID again	Fresh short ID per delivery
E2B dynamic hostname length	May exceed DNS limits for long names	Always within DNS limits

Guidance for clients

• Treat Sandbox IDs as opaque strings. Do not split them on -- or otherwise derive namespace and name from the ID; this breaks as soon as a sandbox receives a short ID.
• If your workflow needs the namespace and name, use the e2b.agents.kruise.io/sandbox-resource metadata returned by E2B-compatible APIs, or query the reserved label with kubectl.
• SDK paths that take namespace and name directly, such as the runtime client's newFromK8s(namespace, sandboxName, ...), are unaffected by this feature.
• Persisted IDs from before enablement (for example in your own records or Checkpoints) stay valid for as long as the corresponding delivery exists; they are never rewritten.

Looking Up a Sandbox by ID

Short IDs are opaque, so use the reserved label to locate the underlying CR:

kubectl get sbx -A -l agents.kruise.io/sandbox-id=<sandbox-id>

E2B diagnostics

E2B-compatible responses intentionally omit namespace and name for short IDs. After sandbox lookup and ownership authorization succeed, the context is restored:

• Successful sandbox metadata includes e2b.agents.kruise.io/sandbox-resource: <namespace>/<name>.
• Downstream runtime, gateway, Checkpoint, and lifecycle errors append sandboxResource=<namespace>/<name>.

Not-found and unauthorized responses do not disclose namespace or name.

Checkpoints and Pagination

• A Checkpoint records the source sandbox's ID at creation time. If that sandbox is later recycled and delivered again, existing Checkpoints keep the prior delivery's ID and new Checkpoints record the new one; history is never rewritten.
• Sandbox listing uses the resolved ID only as an opaque uniqueness component for pagination. An identity transition between list requests may change that component, like other mutable list state.

Rollout and Rollback

Recommended staged rollout:

1. Deploy label-aware sandbox-manager and sandbox-gateway images with short-ID assignment disabled. The two components may be rolled out in either order at this stage.
2. Drain old replicas and their in-flight traffic.
3. Verify informer synchronization on the new replicas.
4. Enable --enable-short-sandbox-id on sandbox-manager.

Rollback notes:

• Once any short ID has been persisted, do not roll back to binaries that ignore the label: such a binary would reconstruct the legacy ID and disagree with the persisted identity.
• If you previously ran an earlier sandbox-manager build that generated short IDs with a different bit layout under the same prefix, choose a prefix that was never used in that environment before enabling the current implementation.