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.

Set, update, and filter on tags from the JS SDK using Sandbox.create(), sandbox.update(), and Sandbox.list().

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

import { Sandbox } from '@vercel/sandbox';
 
const sandbox = await Sandbox.create({
  name: 'my-sandbox',
  tags: { env: 'staging' },
});

Use sandbox.update() to change a sandbox's tags at any time. The provided object replaces the existing tag set, so pass every tag you want to keep:

await sandbox.update({
  tags: { env: 'production', team: 'infra' },
});

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

const productionSandboxes = await Sandbox.list({
  tags: { env: 'production' },
});
 
for await (const sandbox of productionSandboxes) {
  console.log(sandbox.name);
}

The sandbox CLI mirrors the SDK: use --tag on creation, sandbox config tags to update, and --tag on sandbox list to filter.

Use --tag key=value (repeatable) on sandbox create or sandbox run:

sandbox create --name my-sandbox --tag env=staging --tag team=infra

sandbox config tags replaces the full tag set in one call. Pass every tag you want to keep:

sandbox config tags my-sandbox --tag env=production --tag team=infra

Omit --tag to clear all tags.

Pass --tag key=value to sandbox list to narrow the result set:

sandbox list --tag env=production

Tags have a few hard limits to keep in mind when designing your tagging scheme:

• Each sandbox supports a maximum of five tags.
• Sandbox.list() and sandbox list support filtering by one tag at a time.

• Persistent sandboxes: Learn how persistent sandboxes automatically save and restore state.
• JS SDK Reference: Full API documentation for the JavaScript SDK.
• Python SDK Reference: Full API documentation for the Python SDK.
• CLI Reference: Command reference for the CLI.