---
title: Tags
product: vercel
url: /docs/vercel-sandbox/concepts/tags
type: conceptual
prerequisites:
  - /docs/vercel-sandbox/concepts
  - /docs/vercel-sandbox
related:
  - /docs/vercel-sandbox/concepts/persistent-sandboxes
  - /docs/vercel-sandbox/sdk-reference
  - /docs/vercel-sandbox/cli-reference
summary: Learn about tags on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Tags

> **🔒 Permissions Required**: Sandbox tags

Tags let you categorize sandboxes by environment, team, or any other criteria. Each sandbox supports up to five key-value tags that you can set during creation, update at any time, and filter on when listing sandboxes.

## Install the beta packages

> **⚠️ Warning:** Sandbox tags are in beta. Use them in a new project for testing and avoid
> production workloads until the feature is generally available.

Install the beta SDK and CLI:

#### npm

```bash filename="Terminal"
# SDK
npm install @vercel/sandbox@beta

# CLI
npm install -g sandbox@beta
```

#### yarn

```bash filename="Terminal"
# SDK
yarn add @vercel/sandbox@beta

# CLI
yarn global add sandbox@beta
```

#### pnpm

```bash filename="Terminal"
# SDK
pnpm install @vercel/sandbox@beta

# CLI
pnpm install -g sandbox@beta
```

#### bun

```bash filename="Terminal"
# SDK
bun add @vercel/sandbox@beta

# CLI
bun add -g sandbox@beta
```

## SDK usage

### Create a sandbox with tags

Pass the `tags` field when creating a sandbox. You can assign up to five key-value tags:

```ts filename="index.ts"  highlight={5}
import { Sandbox } from '@vercel/sandbox';

const sandbox = await Sandbox.create({
  name: 'my-sandbox',
  tags: { env: 'staging' },
});
```

### Update tags

Use `sandbox.update()` to change a sandbox's tags at any time:

```ts filename="index.ts"
await sandbox.update({
  tags: { env: 'production', team: 'infra' },
});
```

### Filter sandboxes by tag

Pass a `tags` object to `Sandbox.list()` to filter results. You can filter by up to one tag at a time:

```ts filename="index.ts"
const productionSandboxes = await Sandbox.list({
  tags: { env: 'production' },
});

console.log(
  'Production sandboxes:',
  productionSandboxes.sandboxes.map((s) => s.name),
); // my-sandbox
```

## Limitations

- Each sandbox supports a maximum of five tags.
- `Sandbox.list()` supports filtering by one tag at a time.

## Next steps

- [Persistent sandboxes](/docs/vercel-sandbox/concepts/persistent-sandboxes): Learn how persistent sandboxes automatically save and restore state.
- [SDK Reference](/docs/vercel-sandbox/sdk-reference): Full API documentation for the stable SDK.
- [CLI Reference](/docs/vercel-sandbox/cli-reference): Command reference for the stable CLI.


---

[View full sitemap](/docs/sitemap)