> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes

> What a sandbox is, how to find it again, and what runs inside.

A sandbox is a KVM microVM started from a [template](/docs/concepts/templates.md). It has its own Linux kernel, a writable root filesystem, and its own network policy. Inside it, E2B's `envd` daemon serves commands, files and terminals on port 49983; the SDKs and the CLI talk to it through the Anona gateway.

| Property | Value |
| - | - |
| ID | An opaque string such as `i3k2…`; use it to connect, delete or view the sandbox |
| OS | Ubuntu 24.04 |
| User | `user` (uid 1000), home `/home/user`, passwordless `sudo` |
| Size | Small, Medium, Large or XL (`size` at create; see [Sandbox sizes](/docs/concepts/sizes.md)), each with its vCPU, memory and disk. Without a size, the template's own (for example 2 vCPU and 1 GiB for `base`) |
| State | `running` or `paused`; a deleted sandbox is gone |
| Lifetime | A timeout from now, or no deadline; see [Lifecycle](/docs/concepts/lifecycle.md) |

## Metadata and listing

Attach string metadata at create time, then filter on it when you list:

```python metadata.py
from anona_compute import Sandbox
from e2b import SandboxQuery

sbx = Sandbox.create("base", metadata={"job": "nightly-eval", "owner": "ci"})

for info in Sandbox.list(query=SandboxQuery(metadata={"job": "nightly-eval"})).next_items():
    print(info.sandbox_id, info.template_id, info.metadata)

info = sbx.get_info()
print(info.state, info.started_at, info.end_at)
sbx.kill()
```

```typescript metadata.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base", { metadata: { job: "nightly-eval", owner: "ci" } });

const page = await Sandbox.list({ query: { metadata: { job: "nightly-eval" } } }).nextItems();
for (const info of page) console.log(info.sandboxId, info.templateId, info.metadata);

const info = await sbx.getInfo();
console.log(info.state, info.startedAt, info.endAt);
await sbx.kill();
```

```bash metadata.sh
SANDBOX_ID=$(anona-compute create -t base --metadata job=nightly-eval --json | jq -r .sandbox_id)
anona-compute list --metadata job=nightly-eval
anona-compute info "$SANDBOX_ID"
anona-compute delete "$SANDBOX_ID"
```

Metadata keys starting with `anona.` are reserved and refused, and so are the keys the sandbox engine uses itself, such as `host-mount` and anything starting with `cube.` or `io.kubernetes.`, in any letter case. The `400` names the key.

### Names

A sandbox can carry a human name: the `name` metadata key. Set it with
`metadata={"name": "nightly-eval"}`, `anona-compute create --name nightly-eval`
or the **Name** field of **New sandbox**; the dashboard and `anona-compute list`
show it beside the ID, and `anona-compute list --name nightly-eval` (or the
metadata filter) finds it. Change it later with `anona-compute rename` or
`PUT /v1/sandboxes/{id}/name`, which take 1 to 64 letters, digits, spaces, dots,
dashes or underscores. The sandbox ID stays the identifier: every API call and
command still takes the ID.

## Connect from anywhere

A sandbox outlives the process that created it. Any process holding an API key of the same organization can reconnect by ID:

```python connect.py
import os
from anona_compute import Sandbox

sbx = Sandbox.connect(os.environ["SANDBOX_ID"])
print(sbx.commands.run("hostname").stdout)
```

```typescript connect.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.connect(process.env.SANDBOX_ID!);
console.log((await sbx.commands.run("hostname")).stdout);
```

Another organization's sandbox answers "not found", exactly like a sandbox that does not exist.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.