Metadata

Overview

Metadata lets you attach custom key-value pairs to sandboxes at creation time. Use metadata to tag sandboxes with identifiers like user IDs, session IDs, environment names, or any other organizational labels. You can then filter sandboxes by metadata when listing them.

Attaching Metadata

Pass a metadata map (string to string) when creating a sandbox:

const sandbox = await client.createSandbox({
  templateID: "base",
  metadata: {
    userId: "user_abc123",
    sessionId: "sess_xyz789",
    environment: "staging",
    purpose: "code-review",
  },
});

Filtering by Metadata

Use metadata to find specific sandboxes when listing:

const sandboxes = await client.listSandboxes({
  metadata: {
    userId: "user_abc123",
  },
});

for (const sb of sandboxes) {
  console.log(sb.sandboxID, sb.metadata);
}

This is particularly useful when your application manages sandboxes for multiple users or workflows and needs to look up the right sandbox later.

Use Cases