> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata tags

> Attach string key-value tags to sandboxes, update them later, and filter sandboxes by tag.

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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const sandbox = await Sandbox.create({
    name: "data-analyzer",
    metadata: {
      env: "prod",
      owner: "agent-7",
      job_id: "job_01HE...",
    },
  })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  sandbox = Sandbox.create(
      name="data-analyzer",
      metadata={
          "env": "prod",
          "owner": "agent-7",
          "job_id": "job_01HE...",
      },
  )
  ```
</CodeGroup>

## Update metadata

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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  await sandbox.update({
    metadata: { env: "staging", owner: "agent-7" },
  })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  sandbox.update(metadata={"env": "staging", "owner": "agent-7"})
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const prodForAgent = await Sandbox.list({
    metadata: { env: "prod", owner: "agent-7" },
  })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  prod_for_agent = Sandbox.list(
      metadata={"env": "prod", "owner": "agent-7"},
  )
  ```
</CodeGroup>

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