> ## Documentation Index
> Fetch the complete documentation index at: https://e2b.manicule.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://e2b.manicule.dev/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://e2b.manicule.dev/api/mcp.
> Every agent surface: https://e2b.manicule.dev/.well-known/llms-manifest.json

# Sandbox metadata (/docs/sandbox/metadata)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 354 · updated: 2026-07-30 -->
Related: [Auto-resume on request](/docs/sandbox/auto-resume.md), [Connect to running sandbox](/docs/sandbox/connect.md), [Environment variables](/docs/sandbox/environment-variables.md), [Filesystem-only snapshots](/docs/sandbox/filesystem-only-snapshots.md), [Sandbox forking](/docs/sandbox/fork.md), [Git integration](/docs/sandbox/git-integration.md)

Metadata is a way to attach arbitrary key-value pairs for a sandbox.

This is useful in various scenarios, for example:

* Associate a sandbox with a user session.
* Store custom user data for a sandbox like API keys.
* Associate a sandbox with a user ID and [connect to it later](/docs/sandbox/connect).

You specify metadata when creating a sandbox and can access it later through listing running sandboxes with `Sandbox.list()` method.

<CodeGroup>
```js title="JavaScript & TypeScript" highlight={6}
import { Sandbox } from 'e2b'

// Create sandbox with metadata.
const sandbox = await Sandbox.create({
  metadata: {
    userId: '123',
  },
})

// List running sandboxes and access metadata.
const paginator = await Sandbox.list()
const runningSandboxes = await paginator.nextItems()
// Will print:
// {
//   'userId': '123',
// }
console.log(runningSandboxes[0].metadata)
```

```python title="Python" highlight={6}
from e2b import Sandbox

# Create sandbox with metadata.
sandbox = Sandbox.create(
  metadata={
    'userId': '123',
  },
)

# List running sandboxes and access metadata.
paginator = Sandbox.list()
running_sandboxes = paginator.next_items()
# Will print:
# {
#   'userId': '123',
# }
print(running_sandboxes[0].metadata)
```
</CodeGroup>

## Filtering sandboxes by metadata

You can also filter sandboxes by metadata, you can find more about it [here](/docs/sandbox/list#filtering-sandboxes).