# Sandbox Metadata - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/guides/sandbox-metadata

# Sandbox Metadata

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()`.

JavaScript & TypeScript

Python

```
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' }
```

```
from novita_sandbox.core import Sandbox

# Start a sandbox and attach custom metadata.
sbx = Sandbox.create(
metadata={
"userId": "123",
},
)

# Retrieve active sandboxes and inspect their metadata.
page = Sandbox.list()
active = page.next_items()

print(active[0].metadata)
# Example output:
# {"userId": "123"}
```

##

[​](#metadata-based-filtering)

Metadata-based filtering

Sandboxes can also be filtered using metadata when listing.

Last modified on June 4, 2026