anona-compute 0.2.0__tar.gz

anona_compute-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+*.tgz
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+.pytest_cache/
+build/

anona_compute-0.2.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: anona-compute
+Version: 0.2.0
+Summary: Anona Compute extras on top of the E2B SDK
+Project-URL: Homepage, https://compute.anonalabs.com
+Project-URL: Documentation, https://compute.anonalabs.com/docs
+Project-URL: Repository, https://github.com/anonalabs/anona-compute-sdk
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: e2b<3,>=2.61
+Provides-Extra: desktop
+Requires-Dist: e2b-desktop<3,>=2.7.2; extra == 'desktop'
+Provides-Extra: test
+Requires-Dist: pytest==9.1.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+# anona-compute (Python)
+
+Optional extras for [Anona Compute](https://compute.anonalabs.com) on top of the stock E2B SDK.
+The stock SDK already works on its own:
+
+```sh
+export E2B_DOMAIN=compute.anonalabs.com
+export E2B_API_KEY=ac_...          # an API key from https://compute.anonalabs.com
+```
+
+This package adds sandbox sizes, live view tokens and SSH certificates.
+
+```sh
+pip install anona-compute
+```
+
+```python
+import anona_compute
+
+anona_compute.configure(api_key="ac_...")       # or set ANONA_API_KEY / E2B_API_KEY
+sbx = anona_compute.Sandbox.create("python", size="large")  # a subclass of e2b.Sandbox
+
+url = sbx.live.url(mode="dom")          # view-only embed URL, 600 s
+tok = sbx.live.token(scope="control", channels=["pty"], ttl=120)
+sbx.live.revoke_all()
+
+cert = sbx.ssh.certificate("~/.ssh/anona_ed25519.pub")
+cert.write("~/.ssh/anona_ed25519-cert.pub")
+print(sbx.ssh.config(identity_file="~/.ssh/anona_ed25519"))
+```
+
+Environment mapping: `ANONA_API_KEY` → `E2B_API_KEY`, `ANONA_DOMAIN` → `E2B_DOMAIN`
+(default `compute.anonalabs.com`), `ANONA_API_URL` → `E2B_API_URL` (deprecated by E2B, fallback only).
+`E2B_*` values always win.
+
+`size` is `small` (1 vCPU, 2 GiB, 10 GB disk), `medium` (2, 4 GiB, 20 GB), `large` (4, 8 GiB, 40 GB) or `xl` (8, 16 GiB, 80 GB). Without it a sandbox runs at its template's own size.
+
+Install the desktop extra with `pip install "anona-compute[desktop]"`.
+
+This is the Python library only. The `anona-compute` command-line tool is a separate npm package: `npm install -g @anona-labs/anona-compute`.
+
+## Development
+
+```sh
+uv venv -p 3.12 .venv && uv pip install -p .venv/bin/python -e ".[test]"
+.venv/bin/python -m pytest -q          # fake gateway, no network
+GATEWAY_URL=... GATEWAY_API_KEY=... .venv/bin/python -m pytest -m gateway
+```
+
+The version comes from the git tag `sdk-v<version>` (hatch-vcs); untagged builds get a `0.0.1.devN+g<sha>` development version.

anona_compute-0.2.0/README.md

@@ -0,0 +1,50 @@
+# anona-compute (Python)
+
+Optional extras for [Anona Compute](https://compute.anonalabs.com) on top of the stock E2B SDK.
+The stock SDK already works on its own:
+
+```sh
+export E2B_DOMAIN=compute.anonalabs.com
+export E2B_API_KEY=ac_...          # an API key from https://compute.anonalabs.com
+```
+
+This package adds sandbox sizes, live view tokens and SSH certificates.
+
+```sh
+pip install anona-compute
+```
+
+```python
+import anona_compute
+
+anona_compute.configure(api_key="ac_...")       # or set ANONA_API_KEY / E2B_API_KEY
+sbx = anona_compute.Sandbox.create("python", size="large")  # a subclass of e2b.Sandbox
+
+url = sbx.live.url(mode="dom")          # view-only embed URL, 600 s
+tok = sbx.live.token(scope="control", channels=["pty"], ttl=120)
+sbx.live.revoke_all()
+
+cert = sbx.ssh.certificate("~/.ssh/anona_ed25519.pub")
+cert.write("~/.ssh/anona_ed25519-cert.pub")
+print(sbx.ssh.config(identity_file="~/.ssh/anona_ed25519"))
+```
+
+Environment mapping: `ANONA_API_KEY` → `E2B_API_KEY`, `ANONA_DOMAIN` → `E2B_DOMAIN`
+(default `compute.anonalabs.com`), `ANONA_API_URL` → `E2B_API_URL` (deprecated by E2B, fallback only).
+`E2B_*` values always win.
+
+`size` is `small` (1 vCPU, 2 GiB, 10 GB disk), `medium` (2, 4 GiB, 20 GB), `large` (4, 8 GiB, 40 GB) or `xl` (8, 16 GiB, 80 GB). Without it a sandbox runs at its template's own size.
+
+Install the desktop extra with `pip install "anona-compute[desktop]"`.
+
+This is the Python library only. The `anona-compute` command-line tool is a separate npm package: `npm install -g @anona-labs/anona-compute`.
+
+## Development
+
+```sh
+uv venv -p 3.12 .venv && uv pip install -p .venv/bin/python -e ".[test]"
+.venv/bin/python -m pytest -q          # fake gateway, no network
+GATEWAY_URL=... GATEWAY_API_KEY=... .venv/bin/python -m pytest -m gateway
+```
+
+The version comes from the git tag `sdk-v<version>` (hatch-vcs); untagged builds get a `0.0.1.devN+g<sha>` development version.

anona_compute-0.2.0/anona_compute/__init__.py

@@ -0,0 +1,55 @@
+"""Anona Compute extras on top of the E2B SDK.
+
+The stock E2B SDK works against Anona with ``E2B_DOMAIN=compute.anonalabs.com``
+and ``E2B_API_KEY``; this package is optional. It adds:
+
+- ``anona_compute.configure(api_key=...)`` and ``anona_compute.Sandbox``, a subclass of
+  ``e2b.Sandbox`` that defaults to the Anona domain.
+- ``sandbox.live``: viewer tokens and embed URLs for the live view.
+- ``sandbox.ssh``: short-lived SSH certificates and an ``ssh_config`` snippet.
+- ``sandbox.idle_pause``: pause the sandbox once nothing has used it for a while.
+
+Environment mapping (only variables the E2B SDK 2.61.0 reads in
+``e2b/connection_config.py`` are targeted):
+
+==================  ==============  ==========================================
+Anona variable      E2B variable    Notes
+==================  ==============  ==========================================
+``ANONA_API_KEY``   ``E2B_API_KEY`` used when ``E2B_API_KEY`` is unset
+``ANONA_DOMAIN``    ``E2B_DOMAIN``  default ``compute.anonalabs.com``
+``ANONA_API_URL``   ``E2B_API_URL`` deprecated by E2B; fallback only
+==================  ==============  ==========================================
+
+``E2B_*`` values always win over ``ANONA_*`` values.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from anona_compute._config import DEFAULT_API_URL, DEFAULT_DOMAIN, ENV_MAP, configure
+from anona_compute.idle import MAX_IDLE_PAUSE_MINUTES, IdlePause
+from anona_compute.live import Live, ViewerToken
+from anona_compute.sandbox import SIZES, Sandbox, SandboxSize, size_metadata
+from anona_compute.ssh import Ssh, SshCertificate
+
+try:
+    __version__ = _version("anona-compute")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0"
+
+__all__ = [
+    "DEFAULT_API_URL",
+    "DEFAULT_DOMAIN",
+    "ENV_MAP",
+    "MAX_IDLE_PAUSE_MINUTES",
+    "IdlePause",
+    "Live",
+    "SIZES",
+    "Sandbox",
+    "SandboxSize",
+    "Ssh",
+    "SshCertificate",
+    "ViewerToken",
+    "size_metadata",
+    "__version__",
+    "configure",
+]

anona_compute-0.2.0/anona_compute/_config.py

@@ -0,0 +1,82 @@
+"""Environment mapping between Anona settings and the variables the E2B SDK reads.
+
+The E2B Python SDK 2.61.0 reads these variables in ``e2b/connection_config.py``:
+``E2B_API_KEY``, ``E2B_DOMAIN``, ``E2B_API_URL`` (deprecated), ``E2B_SANDBOX_URL``
+(deprecated), ``E2B_DEBUG`` and ``E2B_HTTP_VERSION``. Only the first four that
+matter for pointing the SDK at Anona are mapped here; no new E2B variables are
+invented.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Mapping, MutableMapping, Optional
+
+DEFAULT_DOMAIN = "compute.anonalabs.com"
+"""Domain customers set as ``E2B_DOMAIN``. The SDK derives ``https://api.<domain>``."""
+
+DEFAULT_API_URL = f"https://api.{DEFAULT_DOMAIN}"
+"""Public API endpoint. Only used directly by the Anona extras."""
+
+# Anona variable -> E2B variable. ANONA_* wins only when the E2B variable is unset,
+# so a customer who already exported E2B_* keeps full control.
+ENV_MAP: Mapping[str, str] = {
+    "ANONA_API_KEY": "E2B_API_KEY",
+    "ANONA_DOMAIN": "E2B_DOMAIN",
+    "ANONA_API_URL": "E2B_API_URL",
+}
+
+
+COMPUTE_KEY_PREFIXES = ("ac_", "e2b_")
+"""Prefixes of an Anona Compute API key (``ac_``, legacy ``e2b_``)."""
+
+
+def compute_key(value: Optional[str]) -> Optional[str]:
+    """``value`` if it is an Anona Compute key, else ``None``.
+
+    ``ANONA_API_KEY`` is shared with Anona Memory, whose key must never be
+    sent to the compute API. The ``anona-compute`` CLI applies the same rule.
+    """
+    if value and value.startswith(COMPUTE_KEY_PREFIXES):
+        return value
+    return None
+
+
+def apply_env(environ: Optional[MutableMapping[str, str]] = None) -> None:
+    """Copy ``ANONA_*`` values to the ``E2B_*`` names and default ``E2B_DOMAIN``.
+
+    ``ANONA_API_KEY`` is copied only when it holds a compute key.
+    """
+    env = os.environ if environ is None else environ
+    for src, dst in ENV_MAP.items():
+        value = env.get(src)
+        if src == "ANONA_API_KEY":
+            value = compute_key(value)
+        if value and not env.get(dst):
+            env[dst] = value
+    if not env.get("E2B_DOMAIN"):
+        env["E2B_DOMAIN"] = DEFAULT_DOMAIN
+
+
+def configure(
+    api_key: Optional[str] = None,
+    *,
+    domain: Optional[str] = None,
+    api_url: Optional[str] = None,
+    debug: Optional[bool] = None,
+) -> None:
+    """Point the stock E2B SDK (and the Anona extras) at Anona Compute.
+
+    Explicit arguments overwrite the matching ``E2B_*`` variables in this
+    process. Missing values fall back to ``ANONA_*`` variables, then to the
+    defaults (``E2B_DOMAIN=compute.anonalabs.com``).
+    """
+    if api_key is not None:
+        os.environ["E2B_API_KEY"] = api_key
+    if domain is not None:
+        os.environ["E2B_DOMAIN"] = domain
+    if api_url is not None:
+        os.environ["E2B_API_URL"] = api_url
+    if debug is not None:
+        os.environ["E2B_DEBUG"] = "true" if debug else "false"
+    apply_env()

anona_compute-0.2.0/anona_compute/_http.py

@@ -0,0 +1,78 @@
+"""Small HTTP helper for the Anona-only gateway endpoints."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+from e2b.connection_config import ConnectionConfig
+from e2b.exceptions import (
+    AuthenticationException,
+    InvalidArgumentException,
+    NotFoundException,
+    RateLimitException,
+    SandboxException,
+)
+
+
+def _error(resp: httpx.Response) -> Exception:
+    try:
+        body = resp.json()
+        message = body.get("message") or resp.text
+    except ValueError:
+        message = resp.text
+    message = f"{resp.status_code}: {message}"
+    if resp.status_code == 400:
+        return InvalidArgumentException(message)
+    if resp.status_code in (401, 403):
+        return AuthenticationException(message)
+    if resp.status_code == 404:
+        return NotFoundException(message)
+    if resp.status_code == 429:
+        return RateLimitException(message)
+    return SandboxException(message)
+
+
+def _request(
+    config: ConnectionConfig,
+    method: str,
+    path: str,
+    body: Optional[Dict[str, Any]] = None,
+) -> Optional[Dict[str, Any]]:
+    headers = dict(config.headers)
+    if config.api_key:
+        headers["X-API-Key"] = config.api_key
+    with httpx.Client(
+        base_url=config.api_url,
+        timeout=config.request_timeout,
+        proxy=config.proxy,  # type: ignore[arg-type]
+    ) as client:
+        resp = client.request(method, path, json=body, headers=headers)
+    if resp.status_code >= 400:
+        raise _error(resp)
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()
+
+
+def post_json(
+    config: ConnectionConfig,
+    path: str,
+    body: Optional[Dict[str, Any]] = None,
+) -> Optional[Dict[str, Any]]:
+    """POST to ``<api_url><path>`` with the sandbox's API key; return the JSON body."""
+    return _request(config, "POST", path, body)
+
+
+def put_json(
+    config: ConnectionConfig,
+    path: str,
+    body: Optional[Dict[str, Any]] = None,
+) -> Optional[Dict[str, Any]]:
+    """PUT to ``<api_url><path>`` with the sandbox's API key; return the JSON body."""
+    return _request(config, "PUT", path, body)
+
+
+def get_json(config: ConnectionConfig, path: str) -> Optional[Dict[str, Any]]:
+    """GET ``<api_url><path>`` with the sandbox's API key; return the JSON body."""
+    return _request(config, "GET", path)

anona_compute-0.2.0/anona_compute/desktop.py

@@ -0,0 +1,56 @@
+"""``anona_compute.desktop.Sandbox``: the stock ``e2b_desktop.Sandbox`` plus Anona extras.
+
+Every e2b-desktop call (mouse, keyboard, screenshot, ``stream.start`` and the
+noVNC ``stream.get_url``) is inherited unchanged. The additions are the same
+``live`` and ``ssh`` helpers as ``anona_compute.Sandbox`` and ``live_url()``, the
+Anona live-view link for the desktop channel. That channel is served by the
+template's guest broker (VNC on 127.0.0.1:5901, started on first use), so it
+needs no ``stream.start()`` and never exposes port 6080.
+
+Install with ``pip install "anona-compute[desktop]"``.
+"""
+
+from __future__ import annotations
+
+from typing import Unpack
+
+try:
+    import e2b_desktop
+except ImportError as e:  # pragma: no cover - exercised only without the extra
+    raise ImportError('anona_compute.desktop needs e2b-desktop: pip install "anona-compute[desktop]"') from e
+
+from e2b.connection_config import ApiParams
+
+from anona_compute.idle import IdlePause
+from anona_compute.live import MAX_TTL, Live
+from anona_compute.sandbox import anona_defaults
+from anona_compute.ssh import Ssh
+
+
+class Sandbox(e2b_desktop.Sandbox):
+    """``e2b_desktop.Sandbox`` with ``live``, ``ssh``, ``idle_pause`` and ``live_url()``."""
+
+    @classmethod
+    def _resolve_api_params(cls, **opts: Unpack[ApiParams]) -> ApiParams:
+        merged = dict(anona_defaults())
+        resolved = super()._resolve_api_params(**opts)
+        merged.update({k: v for k, v in resolved.items() if v is not None})
+        return merged  # type: ignore[return-value]
+
+    @property
+    def live(self) -> Live:
+        return Live(self.sandbox_id, self.connection_config)
+
+    @property
+    def ssh(self) -> Ssh:
+        return Ssh(self.sandbox_id, self.connection_config)
+
+    @property
+    def idle_pause(self) -> IdlePause:
+        """Idle pause: ``get()``, ``set(minutes)``, ``off()``, as on ``anona_compute.Sandbox``."""
+        return IdlePause(self.sandbox_id, self.connection_config)
+
+    def live_url(self, control: bool = True, ttl: int = MAX_TTL) -> str:
+        """Embed URL for the desktop channel (control scope by default: the
+        desktop channel carries RFB input, which a view token may not send)."""
+        return self.live.url(mode="desktop", scope="control" if control else "view", ttl=ttl)

anona_compute-0.2.0/anona_compute/idle.py

@@ -0,0 +1,72 @@
+"""Idle pause: pause a sandbox once nothing has used it for a while.
+
+Gateway contract (Anona routes, not E2B):
+
+- ``PUT /v1/sandboxes/{id}/auto-pause`` with ``{"idleMinutes": n}`` returns the
+  sandbox's access settings. ``n`` is 1 to 10080 (one week); ``0`` turns idle
+  pausing off.
+- ``GET /v1/sandboxes/{id}/access`` returns ``idlePauseMinutes`` among them.
+
+This is **not** the same as E2B's ``autoPause``/``on_timeout``, which decides what
+happens when the sandbox's *deadline* runs out. Idle pause has no deadline: the
+sandbox keeps running for as long as it is used, and pauses once it is not.
+
+What counts as use, so the clock restarts: any
+request to any of the sandbox's ports except envd's ``GET /health``; an open live
+view, terminal, SSH session or byte pipe; and any process envd started that is
+still running. Not counted: CPU burned inside the guest by something envd did not
+start, outbound traffic the sandbox makes itself, and API calls *about* the
+sandbox. A sandbox busy on work it started by itself will still pause.
+
+Resume with ``Sandbox.connect(sandbox_id)``.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+from typing import TYPE_CHECKING
+
+from e2b.exceptions import InvalidArgumentException
+
+from anona_compute._http import get_json, put_json
+
+if TYPE_CHECKING:
+    from e2b.connection_config import ConnectionConfig
+
+#: Longest idle time the gateway accepts (store.MaxIdlePauseMinutes): one week.
+MAX_IDLE_PAUSE_MINUTES = 10080
+
+
+class IdlePause:
+    """``sandbox.idle_pause``: read and set this sandbox's idle-pause time."""
+
+    def __init__(self, sandbox_id: str, config: "ConnectionConfig"):
+        self._sandbox_id = sandbox_id
+        self._config = config
+
+    @property
+    def _path(self) -> str:
+        return f"/v1/sandboxes/{quote(self._sandbox_id, safe='')}"
+
+    def get(self) -> int:
+        """Minutes of idleness before this sandbox pauses; ``0`` when off."""
+        body = get_json(self._config, f"{self._path}/access") or {}
+        return int(body.get("idlePauseMinutes") or 0)
+
+    def set(self, minutes: int) -> int:
+        """Pause this sandbox after ``minutes`` without use. ``0`` turns it off.
+
+        Returns the value the gateway recorded, which is what later reads will show.
+        """
+        if not isinstance(minutes, int) or isinstance(minutes, bool):
+            raise InvalidArgumentException("minutes must be an int")
+        if minutes < 0 or minutes > MAX_IDLE_PAUSE_MINUTES:
+            raise InvalidArgumentException(
+                f"minutes must be 0 (off) to {MAX_IDLE_PAUSE_MINUTES}"
+            )
+        body = put_json(self._config, f"{self._path}/auto-pause", {"idleMinutes": minutes}) or {}
+        return int(body.get("idlePauseMinutes") or 0)
+
+    def off(self) -> int:
+        """Stop pausing this sandbox when it is idle. Same as ``set(0)``."""
+        return self.set(0)

anona_compute-0.2.0/anona_compute/live.py

@@ -0,0 +1,106 @@
+"""Live view helpers: mint viewer tokens and embed URLs, revoke viewers.
+
+Gateway contract (plan 05, section 3.4):
+
+- ``POST /v1/sandboxes/{id}/viewer-tokens`` with
+  ``{"scope": "view"|"control", "channels": [...], "ttlSeconds": n}`` returns
+  ``{"token", "expiresAt", "embedUrl"}``.
+- ``POST /v1/sandboxes/{id}/viewer-tokens:revoke-all`` returns 200 ``{"epoch": n}``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional
+from urllib.parse import quote
+
+from e2b.exceptions import InvalidArgumentException
+
+from anona_compute._http import post_json
+
+if TYPE_CHECKING:
+    from e2b.connection_config import ConnectionConfig
+
+SCOPES = ("view", "control")
+CHANNELS = ("dom", "pty", "desktop", "thumb")
+MIN_TTL = 30
+MAX_TTL = 600
+
+
+@dataclass(frozen=True)
+class ViewerToken:
+    """A signed viewer token. ``repr`` never prints the token itself."""
+
+    token: str = field(repr=False)
+    expires_at: datetime
+    embed_url: str = field(repr=False)
+
+    def claims(self) -> Dict[str, Any]:
+        """Decode the JWS payload without checking the signature (for inspection only)."""
+        parts = self.token.split(".")
+        if len(parts) != 3:
+            raise ValueError("viewer token is not a compact JWS")
+        payload = parts[1] + "=" * (-len(parts[1]) % 4)
+        return json.loads(base64.urlsafe_b64decode(payload))
+
+
+def _parse_time(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _validate(scope: str, channels: List[str], ttl: int) -> None:
+    if scope not in SCOPES:
+        raise InvalidArgumentException(f"scope must be one of {SCOPES}, got {scope!r}")
+    if not channels:
+        raise InvalidArgumentException("channels must not be empty")
+    unknown = [c for c in channels if c not in CHANNELS]
+    if unknown:
+        raise InvalidArgumentException(f"unknown channels {unknown}; allowed {CHANNELS}")
+    # The gateway decodes ttlSeconds into an int and answers 400 to 60.5, so a
+    # fraction is refused here, as the TypeScript SDK does (Number.isInteger).
+    if isinstance(ttl, bool) or not isinstance(ttl, int) or not MIN_TTL <= ttl <= MAX_TTL:
+        raise InvalidArgumentException(f"ttl must be a whole number of seconds from {MIN_TTL} to {MAX_TTL}")
+
+
+class Live:
+    """``sandbox.live``: viewer tokens for the live view of one sandbox."""
+
+    def __init__(self, sandbox_id: str, config: "ConnectionConfig"):
+        self._sandbox_id = sandbox_id
+        self._config = config
+
+    def _path(self, suffix: str = "") -> str:
+        return f"/v1/sandboxes/{quote(self._sandbox_id, safe='')}/viewer-tokens{suffix}"
+
+    def token(
+        self,
+        scope: str = "view",
+        channels: Optional[Iterable[str]] = None,
+        ttl: int = MAX_TTL,
+    ) -> ViewerToken:
+        """Mint a viewer token (default: view-only DOM channel, 600 s)."""
+        chans = list(channels) if channels is not None else ["dom"]
+        _validate(scope, chans, ttl)
+        body = post_json(
+            self._config,
+            self._path(),
+            {"scope": scope, "channels": chans, "ttlSeconds": ttl},
+        )
+        if not body:
+            raise InvalidArgumentException("gateway returned an empty viewer token response")
+        return ViewerToken(
+            token=body["token"],
+            expires_at=_parse_time(body["expiresAt"]),
+            embed_url=body["embedUrl"],
+        )
+
+    def url(self, mode: str = "dom", scope: str = "view", ttl: int = MAX_TTL) -> str:
+        """Mint a token for one channel and return its embed URL."""
+        return self.token(scope=scope, channels=[mode], ttl=ttl).embed_url
+
+    def revoke_all(self) -> None:
+        """Close every open viewer of this sandbox and invalidate issued tokens."""
+        post_json(self._config, self._path(":revoke-all"))

anona_compute-0.2.0/anona_compute/sandbox.py

@@ -0,0 +1,94 @@
+"""``anona_compute.Sandbox``: the stock ``e2b.Sandbox`` plus Anona defaults and extras."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Literal, Unpack
+
+import e2b
+from e2b.connection_config import ApiParams
+
+from anona_compute._config import DEFAULT_DOMAIN, compute_key
+from anona_compute.idle import IdlePause
+from anona_compute.live import Live
+from anona_compute.ssh import Ssh
+
+
+SandboxSize = Literal["small", "medium", "large", "xl"]
+SIZES: tuple[str, ...] = ("small", "medium", "large", "xl")
+_SIZE_ALIASES = {"s": "small", "m": "medium", "l": "large", "xlarge": "xl", "x-large": "xl"}
+
+# The E2B SDK cannot send the create body's ``size`` (an Anona extension), so
+# the size rides in this metadata key; the gateway consumes it and never
+# stores it as metadata.
+SIZE_METADATA_KEY = "anona.size"
+
+
+def size_metadata(size: str, metadata: dict[str, str] | None = None) -> dict[str, str]:
+    """Return ``metadata`` with the sandbox size set (small, medium, large or xl)."""
+    name = _SIZE_ALIASES.get(size.strip().lower(), size.strip().lower())
+    if name not in SIZES:
+        raise ValueError(f"unknown sandbox size {size!r}: use one of {', '.join(SIZES)}")
+    out = dict(metadata or {})
+    out[SIZE_METADATA_KEY] = name
+    return out
+
+
+def anona_defaults() -> ApiParams:
+    """API params that point the SDK at Anona unless E2B_* variables say otherwise."""
+    params: ApiParams = {}
+    if not os.getenv("E2B_DOMAIN"):
+        params["domain"] = os.getenv("ANONA_DOMAIN") or DEFAULT_DOMAIN
+    key = compute_key(os.getenv("ANONA_API_KEY"))
+    if not os.getenv("E2B_API_KEY") and key:
+        params["api_key"] = key
+    if not os.getenv("E2B_API_URL") and os.getenv("ANONA_API_URL"):
+        params["api_url"] = os.environ["ANONA_API_URL"]
+    return params
+
+
+class Sandbox(e2b.Sandbox):
+    """Every ``e2b.Sandbox`` method works unchanged; ``live``, ``ssh`` and ``idle_pause`` are added."""
+
+    @classmethod
+    def _resolve_api_params(cls, **opts: Unpack[ApiParams]) -> ApiParams:
+        merged = dict(anona_defaults())
+        resolved = super()._resolve_api_params(**opts)
+        merged.update({k: v for k, v in resolved.items() if v is not None})
+        return merged  # type: ignore[return-value]
+
+    @classmethod
+    def create(cls, template: str | None = None, *args: Any, size: str | None = None, **kwargs: Any):  # type: ignore[override]
+        """``e2b.Sandbox.create`` plus ``size``: small, medium, large or xl.
+
+        A size decides the sandbox's vCPU, memory and disk; without one the
+        sandbox runs at its template's own size. A size below the template's
+        minimum, or not in your plan, is refused with the sizes that would work.
+        """
+        if size is not None:
+            if len(args) >= 2:  # timeout, metadata given positionally
+                lst = list(args)
+                lst[1] = size_metadata(size, lst[1])
+                args = tuple(lst)
+            else:
+                kwargs["metadata"] = size_metadata(size, kwargs.get("metadata"))
+        return super().create(template, *args, **kwargs)
+
+    @property
+    def live(self) -> Live:
+        """Live view: ``token()``, ``url()``, ``revoke_all()``."""
+        return Live(self.sandbox_id, self.connection_config)
+
+    @property
+    def ssh(self) -> Ssh:
+        """SSH: ``certificate(public_key)`` and ``config()``."""
+        return Ssh(self.sandbox_id, self.connection_config)
+
+    @property
+    def idle_pause(self) -> IdlePause:
+        """Idle pause: ``get()``, ``set(minutes)``, ``off()``.
+
+        Pauses the sandbox once nothing has used it for that long. Different from
+        E2B's ``on_timeout``, which acts when the deadline runs out.
+        """
+        return IdlePause(self.sandbox_id, self.connection_config)