Skip to main content
Sandbox metadata lets you attach custom key-value information to a sandbox. Common uses include:
  • Connecting a sandbox to a user session.
  • Saving custom user-related data for a sandbox, such as API keys.
  • Linking a sandbox to a user ID so it can be reconnected later.
Metadata is provided when the sandbox is created. Later, it can be read when listing active sandboxes with Sandbox.list(). 
import { Sandbox } from 'novita-sandbox'

// Start a sandbox and attach custom metadata.
const sbx = await Sandbox.create({
  metadata: {
    userId: '123',
  },
})

// Retrieve active sandboxes and inspect their metadata.
const page = await Sandbox.list()
const active = await page.nextItems()

console.log(active[0].metadata)
// Example output:
// { userId: '123' }

ā€‹
Metadata-based filtering

Sandboxes can also be filtered using metadata when listing.
Last modified on June 4, 2026