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

# A sandbox for each of your users

> One sandbox per end user of your app: find it again by metadata, pause it when idle, show it in your own page.

**You want** your product to give every one of its users a computer: a notebook, a coding workspace, an agent that works on their files. Each user gets their own sandbox, it is still there when they come back, and you show it inside your own UI.

**Why it fits.** Sandboxes are isolated from each other by their own kernel ([Security](/docs/concepts/security.md)). A paused sandbox keeps its memory and files, costs only storage, and does not count towards your plan's sandboxes at once ([Limits](/docs/concepts/limits.md)). So the number that matters is users active right now, not users in total.

**1. Tag each sandbox with your user's ID**

Keep the API key on your server. Find the user's sandbox by metadata, resume it if it exists, create it if not:

```python sandbox_for_user.py
from anona_compute import Sandbox
from e2b import SandboxQuery, SandboxState

def sandbox_for(user_id: str) -> Sandbox:
    # Ask for paused sandboxes too: a returning user's sandbox is usually paused.
    query = SandboxQuery(metadata={"app_user": user_id}, state=[SandboxState.RUNNING, SandboxState.PAUSED])
    found = Sandbox.list(query=query).next_items()
    if found:
        return Sandbox.connect(found[0].sandbox_id)  # resumes it if paused
    sbx = Sandbox.create("base", timeout=3600, metadata={"app_user": user_id})
    sbx.idle_pause.set(15)  # pause after 15 minutes nobody uses it
    return sbx

sbx = sandbox_for("user_42")
assert sandbox_for("user_42").sandbox_id == sbx.sandbox_id  # the same one, found again
sbx.kill()
```

Keys starting with `anona.` are reserved; pick your own prefix. On plans without a maximum lifetime, `timeout=-1` removes the deadline and idle pause alone decides ([Lifecycle](/docs/concepts/lifecycle.md#no-time-limit)).

**2. Show it in your page**

Your server mints a short-lived viewer token and your page puts the URL in an iframe. `pty` gives the user a terminal, `desktop` a screen:

```python viewer_url.py
from anona_compute import Sandbox

sbx = Sandbox.create("base", timeout=300)
try:
    url = sbx.live.url(mode="pty", scope="control", ttl=300)  # send this to the browser
    print(url.split("#")[0])  # the token is in the fragment, which never reaches a server
finally:
    sbx.kill()
```

Tokens last up to 10 minutes; the embed asks your page for a fresh one before that. See [Embed it](/docs/guides/live-view.md#embed-it). To show a web app the user built, use a [preview link](/docs/guides/preview-links.md) instead.

**3. Keep your own records in step**

Subscribe a [webhook](/docs/guides/webhooks.md) to `sandbox.lifecycle.paused`, `resumed` and `killed`, and update your database from it rather than polling. Deliveries are at least once and unordered: deduplicate on `webhook-id` and order by `timestamp`.

**4. Know what each user costs**

[OpenTelemetry export](/docs/guides/webhooks.md#opentelemetry-export) sends per-sandbox CPU, memory and network to your own backend every minute, tagged with the sandbox ID, so you can bill or limit per user.

> [!WARNING]
>
> Never send your API key to the browser. Everything the page needs (a viewer token, a preview link) is minted by your server and expires on its own.

**Runnable example:** [`examples/python/sandbox_per_user.py`](https://github.com/anonalabs/anona-compute-sdk/blob/main/examples/python/sandbox_per_user.py) in the public SDK repository. It prints what happens at each step.


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