Metadata tags - Superserve

Metadata is a flat {string: string} map attached to each sandbox. Use it to track the user, job, environment, or any other context you need to query later.

Set metadata on create

const sandbox = await Sandbox.create({
  name: "data-analyzer",
  metadata: {
    env: "prod",
    owner: "agent-7",
    job_id: "job_01HE...",
  },
})

sandbox = Sandbox.create(
    name="data-analyzer",
    metadata={
        "env": "prod",
        "owner": "agent-7",
        "job_id": "job_01HE...",
    },
)

Update metadata

update() replaces the metadata map - pass the full set you want to keep.

await sandbox.update({
  metadata: { env: "staging", owner: "agent-7" },
})

sandbox.update(metadata={"env": "staging", "owner": "agent-7"})

Filter sandboxes by metadata

Sandbox.list() accepts a metadata filter. Multiple keys combine with AND - a sandbox must match every key-value pair to be returned.

const prodForAgent = await Sandbox.list({
  metadata: { env: "prod", owner: "agent-7" },
})

prod_for_agent = Sandbox.list(
    metadata={"env": "prod", "owner": "agent-7"},
)

The sandbox.metadata instance property is a snapshot taken at construction. Call getInfo() / get_info() to fetch the current metadata after an update().