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

# Python: anona-compute

> anona_compute.Sandbox, live view tokens and SSH certificates.

```text
pip install anona-compute              # or: pip install "anona-compute[desktop]"
```

## `anona_compute.configure`

```python Signature
anona_compute.configure(api_key=None, *, domain=None, api_url=None, debug=None,
                        wait_for_capacity=None, on_capacity_wait=None) -> None
```

Sets the `E2B_*` variables of this process so the stock SDK, and the extras, talk to Anona. Missing values fall back to `ANONA_*` variables, then to `E2B_DOMAIN=compute.anonalabs.com`. `wait_for_capacity` and `on_capacity_wait` set the default [capacity wait](#waiting-for-capacity) of `anona_compute.Sandbox` in this process.

```python configure.py
import os
import anona_compute
from e2b import Sandbox  # the stock SDK picks up the configuration

anona_compute.configure(api_key=os.environ["ANONA_API_KEY"])
with Sandbox.create() as sbx:
    print(sbx.commands.run("echo configured").stdout)
```

## `anona_compute.Sandbox`

A subclass of `e2b.Sandbox`. Every E2B method works unchanged; `create`, `connect` and `list` default to the Anona domain. Three properties are added:

| Property | Type |
| - | - |
| `sandbox.live` | `anona_compute.Live` |
| `sandbox.idle_pause` | `anona_compute.IdlePause`: `get()`, `set(minutes)`, `off()` ([Pause when idle](/docs/concepts/lifecycle.md#pause-when-idle)) |
| `sandbox.ssh` | `anona_compute.Ssh` |

`create` also takes `size` (`"small"`, `"medium"`, `"large"` or `"xl"`), and `create` and `connect` take `wait_for_capacity` and `on_capacity_wait`.

## Waiting for capacity

From `anona-compute` 0.3.0.

When every host is full, the API answers a create with `503` `sandbox_capacity_unavailable`, `Should-Retry: true` and `Retry-After` while it starts another host, which takes a few minutes. `Sandbox.create` and `Sandbox.connect` (which resumes a paused sandbox) then wait and try again instead of raising: after each `Retry-After`, held between 1 and 30 seconds with a little jitter, until the wait runs out. Then the last error is raised unchanged.

| Argument | Default | |
| - | - | - |
| `wait_for_capacity` | `600` | Seconds to keep trying. `0` turns the wait off. The default comes from `configure(wait_for_capacity=...)`, else `ANONA_COMPUTE_CAPACITY_WAIT` (seconds, or a duration such as `10m`; the CLI reads it too), else 10 minutes |
| `on_capacity_wait` | `None` | Called before each wait with an `anona_compute.CapacityWait`: `attempt`, `delay`, `elapsed` and `remaining` (seconds), `status`, `error_code` and `message` |

Each wait is also logged at `INFO` on the `anona_compute` logger.

Only a `503` marked `Should-Retry: true` is retried: no capacity yet (`sandbox_capacity_unavailable`), the platform starting (`sandbox_engine_starting`) or settling (`sandbox_engine_unavailable`), or a size being prepared (`sandbox_size_preparing`). Everything else is raised at once: a plan limit (`403` or `429` `plan_limit_exceeded`), any `4xx`, and a `503` with `Should-Retry: false` or without the header, which comes from something in front of the API and may mean the sandbox already started. Each try keeps your `request_timeout`, and the E2B SDK's own `retries` still apply inside each try.

```python capacity_wait.py
import anona_compute
from anona_compute import Sandbox

def note(wait):
    print(f"no capacity yet ({wait.error_code}); retrying in {wait.delay:.0f}s")

anona_compute.configure(wait_for_capacity=300)  # every create in this process waits up to 5 minutes
sbx = Sandbox.create("base", on_capacity_wait=note)
print(sbx.sandbox_id)
sbx.kill()
```

`anona_compute.desktop.Sandbox` takes the same arguments; only the API call is repeated, not the desktop's start-up. The stock `e2b.Sandbox` and `e2b.AsyncSandbox` do not wait.

## `sandbox.live`

| Method | Returns | |
| - | - | - |
| `token(scope="view", channels=None, ttl=600)` | `ViewerToken` | `scope`: `"view"` or `"control"`. `channels`: any of `"dom"`, `"pty"`, `"desktop"`, `"thumb"` (default `["dom"]`). `ttl`: 30 to 600 seconds |
| `url(mode="dom", scope="view", ttl=600)` | `str` | Mints a token for one channel and returns its embed URL |
| `revoke_all()` | `None` | Closes every open viewer and invalidates issued tokens |

`ViewerToken` has `token`, `expires_at` (`datetime`), `embed_url`, and `claims()` (decodes the payload without verifying it). Its `repr` never shows the token.

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

sbx = Sandbox.connect(os.environ["SANDBOX_ID"])
tok = sbx.live.token(scope="control", channels=["pty"], ttl=120)
print(tok)                       # ViewerToken(expires_at=...)
print(tok.claims()["scp"], tok.claims()["sbx"] == sbx.sandbox_id)
print(sbx.live.url(mode="pty", scope="control").split("#")[0])
```

Invalid arguments raise `e2b.InvalidArgumentException` before any request. Gateway errors map to the E2B exceptions: 400 `InvalidArgumentException`, 401/403 `AuthenticationException`, 404 `NotFoundException`, 429 `RateLimitException`.

## `sandbox.ssh`

| Method | Returns | |
| - | - | - |
| `certificate(public_key)` | `SshCertificate` | `public_key`: an OpenSSH public key string, or the path of a `.pub` file (`ssh-ed25519`, `ecdsa-sha2-nistp256`, `ssh-rsa`). Refuses private keys |
| `config(identity_file="~/.ssh/anona_ed25519", certificate_file=None, alias=None, user="user", proxy_command="anona-compute ssh --proxy %h")` | `str` | An `ssh_config` block. Makes no request |

`SshCertificate` has `cert`, `user`, `host`, `proxy_command`, `expires_at`, and `write(path)` (writes with mode 0600). See [SSH](/docs/guides/ssh.md) for a full example.

## `sandbox.idle_pause`

Pauses the sandbox once nothing has used it for a while. Not the same as
`lifecycle={"on_timeout": "pause"}`, which acts when the **deadline** runs out;
idle pause has no deadline. See [Lifecycle](/docs/concepts/lifecycle.md) for what counts
as use.

| Method | Returns | |
| - | - | - |
| `get()` | `int` | Minutes of idleness before this sandbox pauses; `0` when off |
| `set(minutes)` | `int` | 1 to 10080 (one week); `0` turns it off. Returns what the gateway recorded |
| `off()` | `int` | Same as `set(0)` |

```python idle_pause_sdk.py
from anona_compute import Sandbox

sbx = Sandbox.create("base", timeout=-1)  # no deadline
sbx.idle_pause.set(15)                    # pause after 15 idle minutes
print(sbx.idle_pause.get())               # 15
```

Resume with `Sandbox.connect(sandbox_id)`.

## `anona_compute.desktop.Sandbox`

A subclass of `e2b_desktop.Sandbox` (install `anona-compute[desktop]`) with the same `live`, `ssh` and [capacity wait](#waiting-for-capacity), plus:

| Method | Returns | |
| - | - | - |
| `live_url(control=True, ttl=600)` | `str` | Embed URL of the desktop channel. Control scope by default, since the desktop channel carries input |

See [Desktop](/docs/guides/desktop.md).

## Constants

`anona_compute.DEFAULT_DOMAIN` (`"compute.anonalabs.com"`), `anona_compute.DEFAULT_API_URL`, `anona_compute.ENV_MAP`, `anona_compute.MAX_IDLE_PAUSE_MINUTES` (10080), `anona_compute.DEFAULT_WAIT_FOR_CAPACITY` (600), `anona_compute.__version__`.


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