Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
import inspect
from dataclasses import dataclass, field
from datetime import datetime
from typing import (
Any,
Callable,
Dict,
Iterable,
List,
Literal,
Mapping,
NotRequired,
Optional,
TypedDict,
Unpack,
Union,
cast,
)
from e2b.api.client.models import (
ListedSandbox,
SandboxDetail,
SandboxState,
)
from e2b.api.client.models import (
SandboxAutoResumeConfig as ClientSandboxAutoResumeConfig,
)
from e2b.api.client.models import (
SandboxLifecycle as ClientSandboxLifecycle,
)
from e2b.api.client.models import (
SandboxEgressProxyConfigType0 as ClientSandboxEgressProxyConfig,
)
from e2b.api.client.models import (
SandboxEgressProxyTLSConfigType0 as ClientSandboxEgressProxyTLSConfig,
)
from e2b.api.client.models import (
SandboxNetworkConfig as ClientSandboxNetworkConfig,
)
from e2b.api.client.models import (
SandboxNetworkConfigRules,
)
from e2b.api.client.models import (
SandboxNetworkRule as ClientSandboxNetworkRule,
)
from e2b.api.client.models import (
SandboxNetworkTransform as ClientSandboxNetworkTransform,
)
from e2b.api.client.models import (
SandboxNetworkTransformHeaders as ClientSandboxNetworkTransformHeaders,
)
from e2b.api.client.models import (
SandboxIam as ClientSandboxIam,
)
from e2b.api.client.models import (
SandboxIamToken as ClientSandboxIamToken,
)
from e2b.api.client.models import (
SandboxIamTokens as ClientSandboxIamTokens,
)
from e2b.api.client.models import (
SandboxNetworkUpdateConfig,
)
from e2b.api.client.models import (
SandboxNetworkUpdateConfigRules,
)
from e2b.api import SandboxCreateResponse
from e2b.api.client.models.sandbox import Sandbox as CreatedSandbox
from e2b.api.client.types import UNSET, Unset
from e2b.connection_config import ApiParams
from e2b.exceptions import InvalidArgumentException
from e2b.sandbox.mcp import McpServer as BaseMcpServer
from e2b.sandbox.iam import (
IamTokenPlaceholders,
validate_iam_token_name,
)
from e2b.sandbox.network import ALL_TRAFFIC
from e2b.paginator import PaginatorBase
MAX_FORK_COUNT = 20
def to_sandbox_create_response(sandbox: CreatedSandbox) -> SandboxCreateResponse:
"""Map a created, connected or forked sandbox from the API response."""
return SandboxCreateResponse(
sandbox_id=sandbox.sandbox_id,
sandbox_domain=sandbox.domain if isinstance(sandbox.domain, str) else None,
envd_version=sandbox.envd_version,
envd_access_token=(
sandbox.envd_access_token
if isinstance(sandbox.envd_access_token, str)
else None
),
traffic_access_token=(
sandbox.traffic_access_token
if isinstance(sandbox.traffic_access_token, str)
else None
),
)
def validate_fork_count(count: Any) -> None:
"""Reject a fork count the SDK will not send.
``None`` is left off the request so the API default applies.
"""
if count is None:
return
if (
isinstance(count, bool)
or not isinstance(count, int)
or count < 1
or count > MAX_FORK_COUNT
):
raise InvalidArgumentException(
f"count must be an integer between 1 and {MAX_FORK_COUNT}"
)
class GitHubMcpServerConfig(TypedDict):
"""
Configuration for a GitHub-based MCP server.
"""
run_cmd: str
"""
Command to run the MCP server. Must start a stdio-compatible server.
"""
install_cmd: NotRequired[str]
"""
Command to install dependencies for the MCP server. Working directory is the root of the github repository.
"""
envs: NotRequired[Dict[str, str]]
"""
Environment variables to set in the MCP process.
"""
# Extended MCP server configuration that includes base servers
# and allows dynamic GitHub-based MCP servers with custom run and install commands.
# For GitHub servers, use keys in the format "github/owner/repo"
GitHubMcpServer = Dict[str, Union[GitHubMcpServerConfig, Any]]
# Union type that combines base MCP servers with GitHub-based servers
McpServer = Union[BaseMcpServer, GitHubMcpServer]
class SandboxNetworkTransform(TypedDict):
"""
Transform applied to egress requests matching a :class:`SandboxNetworkRule`.
"""
headers: NotRequired[Dict[str, str]]
"""
Headers to inject into the outbound request. Values override any headers
already present on the request.
"""
@dataclass(frozen=True)
class _SandboxNetworkTransformIam:
"""Workload identity placeholders."""
tokens: Mapping[str, str]
"""
Placeholder for each workload token registered in
:attr:`SandboxOpts.iam`, keyed by token name. ``tokens["aws"]`` is the
string ``"${e2b.identity.tokens.aws}"``, which the egress proxy replaces
with a freshly minted token when it forwards the request.
Reading a name that is not registered raises
:class:`InvalidArgumentException` — the proxy never turns an unregistered
name into a token, so a typo would surface as a confusing auth failure at
the destination.
"""
@dataclass(frozen=True)
class SandboxNetworkTransformContext:
"""
Context passed to a :class:`SandboxNetworkRule` ``transform`` callable. Its
values are literal placeholder strings that the egress proxy resolves per
request, so the secret itself never leaves the platform.
"""
iam: _SandboxNetworkTransformIam
"""Workload identity placeholders."""
SandboxNetworkTransformResolver = Callable[
[SandboxNetworkTransformContext], SandboxNetworkTransform
]
"""
Callable form of ``SandboxNetworkRule.transform``. Invoked once while the
request is being built, with a context of placeholder strings.
"""
class SandboxNetworkRule(TypedDict):
"""
Per-domain rule applied to egress requests.
"""
transform: NotRequired[
Union[SandboxNetworkTransform, SandboxNetworkTransformResolver]
]
"""
Transform applied to requests matching this rule.
Accepts either a static :class:`SandboxNetworkTransform` or a callable that
receives a :class:`SandboxNetworkTransformContext` of placeholder strings —
use the callable to inject a workload identity token the proxy mints per
request::
{
"transform": lambda ctx: {
"headers": {"Authorization": f"Bearer {ctx.iam.tokens['aws']}"},
},
}
"""
SandboxNetworkRules = Dict[str, List[SandboxNetworkRule]]
"""
Map of host (or CIDR / IP) to ordered list of rules applied to outbound
requests for that host. Registering a host here does not allow egress on its
own — the host must also appear in ``SandboxNetworkOpts.allow_out``.
"""
class SandboxNetworkRuleInfo(TypedDict):
"""
Per-domain rule as returned by the sandbox info endpoint. Mirrors
:class:`SandboxNetworkRule` but with ``transform`` always materialized to
the static :class:`SandboxNetworkTransform` shape — no callable variant.
"""
transform: NotRequired[SandboxNetworkTransform]
@dataclass(frozen=True)
class SandboxNetworkSelectorContext:
"""
Context passed to ``allow_out``/``deny_out`` callables.
"""
all_traffic: str
"""All traffic sentinel — equivalent to ``"0.0.0.0/0"``."""
rules: Mapping[str, List[SandboxNetworkRule]]
"""Rules registered in :attr:`SandboxNetworkOpts.rules`."""
SandboxNetworkSelector = Union[
List[str],
Callable[[SandboxNetworkSelectorContext], List[str]],
]
"""
Egress rule list, either a static list of CIDR blocks / IP addresses /
hostnames, or a callable that receives a :class:`SandboxNetworkSelectorContext`
and returns the same.
"""
class SandboxEgressProxyTLSOpts(TypedDict, total=False):
"""
TLS settings for the connection to a BYOP SOCKS5 proxy.
"""
server_name: str
"""
Name to verify the proxy certificate against and send as SNI, up to 253
characters. Defaults to the host part of ``address``; set this only when
the certificate does not match the address.
"""
ca_cert: str
"""
One or more PEM CA certificates, up to 8192 bytes. This replaces the
system trust store rather than adding to it.
"""
class SandboxEgressProxyOpts(TypedDict):
"""
SOCKS5 proxy the sandbox's outbound TCP is tunneled through — "bring your
own proxy".
Tunneling happens on the host, after :attr:`SandboxNetworkOpts.allow_out` /
:attr:`SandboxNetworkOpts.deny_out` filtering, so nothing runs inside the
sandbox and code running there can neither see the proxy nor route around
it. UDP-based traffic — DNS and QUIC/HTTP3 — is not tunneled and leaves the
sandbox the usual way.
Egress fails closed: when the proxy is unreachable or does not speak
SOCKS5, outbound connections fail rather than falling back to a direct
connection.
Pass credentials when the proxy requires them::
sandbox = Sandbox.create(
network={
"egress_proxy": {
"address": "proxy.example.com:1080",
"username": "proxy-user",
"password": "proxy-password",
},
},
)
Set ``"tls": True`` to enable TLS with the system trust store, or pass a
mapping to set a custom server name or CA certificate.
"""
address: str
"""
SOCKS5 proxy address in ``host:port`` form, e.g.
``"proxy.example.com:1080"``. The host can be a hostname or an IP literal;
a hostname is re-resolved at dial time and the resolved address is pinned
for that connection, so a DNS change cannot redirect a connection that is
already being established.
The proxy has to be reachable from E2B's infrastructure: an address that
does not resolve, or that resolves into a private or otherwise internal
range, is rejected before the sandbox exists.
"""
username: NotRequired[str]
"""
SOCKS5 username (`RFC 1929 <https://datatracker.ietf.org/doc/html/rfc1929>`_),
up to 255 bytes. Omit it for a proxy that takes no credentials.
"""
password: NotRequired[str]
"""
SOCKS5 password, up to 255 bytes. Only valid together with
:attr:`username`.
"""
tls: NotRequired[Union[bool, SandboxEgressProxyTLSOpts]]
"""
Connect to the proxy over TLS. The SOCKS5 handshake, credentials, and
tunneled traffic run inside the TLS session; TLS protects only the hop to
the proxy. The certificate is always verified, TLS 1.2 or newer is
required, and failures never fall back to plaintext.
Set to ``True`` to use the system trust store and the host part of
``address`` for SNI. Passing a mapping also enables TLS, with optional
custom ``server_name`` and ``ca_cert``.
"""
class SandboxEgressProxyTLSInfo(TypedDict):
"""
TLS status for the egress proxy connection. The CA certificate is never
returned by the API.
"""
server_name: NotRequired[str]
"""See :attr:`SandboxEgressProxyTLSOpts.server_name`."""
class SandboxEgressProxyInfo(TypedDict):
"""
Egress proxy as returned by the sandbox info endpoint. Mirrors
:class:`SandboxEgressProxyOpts` without ``password`` or ``ca_cert`` — the
API never returns them.
"""
address: str
"""See :attr:`SandboxEgressProxyOpts.address`."""
username: NotRequired[str]
"""See :attr:`SandboxEgressProxyOpts.username`."""
tls: NotRequired[SandboxEgressProxyTLSInfo]
"""Set when TLS to the proxy is on."""
class SandboxNetworkOpts(TypedDict):
"""
Sandbox network configuration options.
"""
allow_out: NotRequired[SandboxNetworkSelector]
"""
Allow outbound traffic from the sandbox to the specified addresses.
If ``allow_out`` is not specified, all outbound traffic is allowed.
Accepts either a static list of CIDR blocks / IP addresses / hostnames, or
a callable that receives a :class:`SandboxNetworkSelectorContext` and
returns the same. ``ctx.all_traffic`` is ``"0.0.0.0/0"``; ``ctx.rules`` is
a read-only view of :attr:`rules`.
Examples:
- Static list: ``["1.1.1.1", "8.8.8.0/24"]``
- Allow only rule-registered hosts:
``lambda ctx: list(ctx.rules.keys())``
"""
deny_out: NotRequired[SandboxNetworkSelector]
"""
Deny outbound traffic from the sandbox to the specified addresses.
Accepts the same shapes as ``allow_out``.
Examples:
- Static list: ``["1.1.1.1", "8.8.8.0/24"]``
- Block all egress: ``lambda ctx: [ctx.all_traffic]``
"""
rules: NotRequired[SandboxNetworkRules]
"""
Per-domain transform rules applied to matching egress HTTP/HTTPS
requests. Keys are domains (e.g. ``"api.example.com"``); values are
ordered lists of :class:`SandboxNetworkRule`.
Registering a host here does not allow egress on its own — the host must
also appear in ``allow_out``. Hosts registered here are exposed to the
``allow_out``/``deny_out`` callables via ``ctx.rules``.
A rule's ``transform`` can also be a callable receiving a
:class:`SandboxNetworkTransformContext`, which is how a workload identity
token from :attr:`SandboxOpts.iam` gets injected without the SDK ever
seeing its value::
rules={
"api.internal.example.com": [
{
"transform": lambda ctx: {
"headers": {
"Authorization": f"Bearer {ctx.iam.tokens['aws']}",
},
},
},
],
}
"""
egress_proxy: NotRequired[SandboxEgressProxyOpts]
"""
Tunnel the sandbox's outbound TCP through a SOCKS5 proxy you operate.
Filtering runs first, so a connection ``deny_out`` blocks never reaches the
proxy, and per-host :attr:`rules` transforms still apply before the
connection is dialed. Omit it to send the sandbox's traffic out directly.
Available on E2B Cloud and in BYOC deployments; a sandbox that names a
proxy on a deployment built from the open source ``e2b-dev/runtime``
repository is rejected as unsupported.
Deny everything except a host, and tunnel what is left::
Sandbox.create(
network={
"allow_out": ["api.example.com"],
"deny_out": lambda ctx: [ctx.all_traffic],
"egress_proxy": {"address": "proxy.example.com:1080"},
},
)
"""
dns_servers: NotRequired[List[str]]
"""
DNS servers the sandbox can reach when ``allow_out`` contains a domain.
Each entry must be an IPv4 address (up to 10 entries), and all traffic to it is allowed.
Leave it out to allow the default nameserver ``8.8.8.8``. Pass a list to
allow those servers instead, or ``[]`` to allow none. Allowed domains still
work without a reachable server, since they are matched by name, not by
IP; add the names you need to ``/etc/hosts``.
This only opens the firewall. It does not change the sandbox's
``/etc/resolv.conf``, which still points at ``8.8.8.8``, so write your own
servers there too. With no domain in ``allow_out`` it has no effect::
Sandbox.create(
network={
"allow_out": ["api.example.com"],
"deny_out": lambda ctx: [ctx.all_traffic],
"dns_servers": ["1.1.1.1"],
},
)
"""
allow_public_traffic: NotRequired[bool]
"""
Controls whether sandbox URLs should be publicly accessible or require authentication.
Defaults to True.
"""
mask_request_host: NotRequired[str]
"""
Allows specifying a custom host mask for all sandbox requests.
Supports ${PORT} variable. Defaults to "${PORT}-sandboxid.e2b.app".
Examples:
- Custom subdomain: `"${PORT}-myapp.example.com"`
"""
https_ports: NotRequired[List[int]]
"""
Ports whose public URLs should connect to the sandbox using HTTPS.
Use this when the service listening on the port serves HTTPS (TLS) itself.
This is not TLS passthrough — traffic is still terminated at the E2B proxy
and re-encrypted on the hop to the sandbox. The backend certificate is not
verified, so self-signed certificates work.
Example: ``Sandbox.create(network={"https_ports": [3000]})``
"""
class SandboxNetworkUpdate(TypedDict, total=False):
"""
Subset of :class:`SandboxNetworkOpts` accepted by ``Sandbox.update_network``.
The update endpoint replaces all egress rules atomically — fields that are
omitted are cleared on the server.
"""
allow_out: SandboxNetworkSelector
"""See :attr:`SandboxNetworkOpts.allow_out`."""
deny_out: SandboxNetworkSelector
"""See :attr:`SandboxNetworkOpts.deny_out`."""
rules: SandboxNetworkRules
"""
See :attr:`SandboxNetworkOpts.rules`. A ``transform`` callable works here
too, but the update payload carries no ``iam`` config, so token names cannot
be checked against the sandbox's registered tokens — every name resolves to
its placeholder and a typo only surfaces at the destination.
"""
egress_proxy: SandboxEgressProxyOpts
"""
See :attr:`SandboxNetworkOpts.egress_proxy`. Sets or replaces the proxy on a
sandbox that is already running, with no restart.
The update replaces the whole configuration instead of merging into it, so
an update that leaves this out stops tunneling and sends the sandbox's
traffic out directly — even when the update was only meant to change the
allow and deny lists. Repeat it in every update that should keep tunneling.
The same replace semantics apply to ``tls``: an update that repeats
``address`` but omits ``tls`` keeps tunneling without TLS.
"""
dns_servers: List[str]
"""
See :attr:`SandboxNetworkOpts.dns_servers`. Leaving it out resets it to
the default, ``8.8.8.8``, like the other fields, so repeat a custom list in
every update that should keep it.
"""
allow_internet_access: bool
"""
Allow sandbox to access the internet. When set to ``False``, it behaves the
same as specifying ``deny_out=["0.0.0.0/0"]`` in the network config.
"""
SandboxIamTokenType = Union[Literal["JWT-SVID"], str]
"""
Workload token type. ``"JWT-SVID"`` is the only type the API accepts in this
version; the set is defined server-side and may grow, so any string is allowed.
"""
class SandboxIamToken(TypedDict):
"""
Workload token definition for sandbox workload identity.
"""
audience: str
"""Audience of the workload token, stored exactly as provided."""
token_type: SandboxIamTokenType
"""Workload token type."""
class SandboxIamOpts(TypedDict, total=False):
"""
Sandbox workload identity configuration. A non-empty ``tokens`` map enables
workload identity for the sandbox.
"""
tokens: Dict[str, SandboxIamToken]
"""
Named workload-token definitions, keyed by a caller-chosen token name.
Values can be created with :meth:`Secret.iam_token`.
A name is interpolated into the ``"${e2b.identity.tokens.<name>}"``
placeholder a network transform resolves, so it cannot be empty or contain
``{``, ``}`` or control characters.
"""
class SandboxNetworkInfo(TypedDict, total=False):
"""
Network configuration as returned by the sandbox info endpoint.
Mirrors :class:`SandboxNetworkOpts` but with ``allow_out``/``deny_out``
always materialized to plain string lists.
"""
allow_out: List[str]
deny_out: List[str]
rules: Dict[str, List[SandboxNetworkRuleInfo]]
egress_proxy: SandboxEgressProxyInfo
"""
Proxy the sandbox's egress is currently tunneled through, absent when it
goes out directly. See :class:`SandboxEgressProxyInfo` for why the password
is missing.
"""
dns_servers: List[str]
"""
DNS servers the sandbox can reach when ``allow_out`` contains a domain. See
:attr:`SandboxNetworkOpts.dns_servers`. Missing means the default,
``8.8.8.8``.
"""
allow_public_traffic: bool
mask_request_host: str
https_ports: List[int]
SnapshotMode = Literal["full", "filesystem"]
"""
What a pause or snapshot persists.
``"full"`` persists the filesystem and the memory (running processes, in-memory
state and open connections); resuming restores the sandbox exactly where it left
off. ``"filesystem"`` persists only the filesystem: smaller and faster to take,
and resuming (or creating a sandbox from the snapshot) cold-boots it from disk,
without the running processes, in-memory state and open connections.
"""
def resolve_snapshot_memory(
field: str,
mode: Optional[SnapshotMode],
keep_memory: Optional[bool] = None,
) -> Union[Unset, bool]:
"""Resolve ``mode`` (or the deprecated ``keep_memory``) into the API's
``memory`` flag.
Unset, it stays ``UNSET`` so the API default (currently a full snapshot)
applies. ``field`` names the option in error messages.
"""
if mode is not None and keep_memory is not None:
raise InvalidArgumentException(
f"Pass either {field} or the deprecated keep_memory, not both."
)
if mode is None:
return keep_memory if keep_memory is not None else UNSET
# Re-check at runtime for callers that bypass the type.
allowed = ("full", "filesystem")
if mode not in allowed:
raise InvalidArgumentException(
f"{field} must be one of: {', '.join(allowed)} (got {mode!r})."
)
return mode == "full"
class SandboxOnTimeoutPause(TypedDict):
"""
Object form of `on_timeout` that auto-pauses the sandbox when the timeout is
reached, optionally controlling the pause snapshot kind via `mode`.
"""
action: Literal["pause"]
"""Auto-pause the sandbox when the timeout is reached."""
mode: NotRequired[SnapshotMode]
"""
What the timeout auto-pause persists. Left unset, it is omitted from the
create request and the API's own default (currently `"full"`) applies. With
`"filesystem"`, the auto-pause drops the in-memory state and persists only
the filesystem; resuming such a sandbox cold-boots (reboots) it from disk,
losing running processes and open connections.
`"filesystem"` cannot be combined with `auto_resume`: auto-resume wakes a
paused sandbox on inbound traffic by restoring its memory snapshot in place,
so the request that woke it hits an already-running process. A
filesystem-only snapshot has no memory to restore — resuming cold-boots it —
so it can't be woken transparently by traffic and must be resumed explicitly
via `connect()`.
"""
keep_memory: NotRequired[bool]
"""
:deprecated: Use `mode` instead: `keep_memory: False` is
`mode: "filesystem"`, `keep_memory: True` is `mode: "full"`.
"""
class SandboxOnTimeoutKill(TypedDict):
"""
Object form of `on_timeout` that kills the sandbox when the timeout is reached.
"""
action: Literal["kill"]
"""Kill the sandbox when the timeout is reached."""
SandboxOnTimeout = Union[
Literal["pause", "kill"], SandboxOnTimeoutPause, SandboxOnTimeoutKill
]
"""
What should happen to the sandbox when the timeout is reached. Either the bare
action (`"pause"` / `"kill"`) or the object form. The object form is a
discriminated union on `action`: `mode` is only accepted alongside
`action: "pause"`. Passing `mode` with `action: "kill"` is a static type error.
"""
class SandboxLifecycle(TypedDict):
"""
Sandbox lifecycle configuration; defines post-timeout behavior and auto-resume
settings. An omitted `on_timeout` leaves the choice to the API (currently
`"kill"`); an omitted `auto_resume` leaves the choice to the API.
"""
on_timeout: SandboxOnTimeout
"""
What should happen to the sandbox when timeout is reached. `"kill"` terminates
the sandbox; `"pause"` pauses it for later resume. Accepts either the bare
action or an object `{"action": "pause", "mode": ...}` /
`{"action": "kill"}` to also control the pause snapshot kind. A value outside
the two actions raises `InvalidArgumentException`. Omitted from the
create request when unset, leaving the API's default (currently `"kill"`) in
effect.
"""
auto_resume: NotRequired[bool]
"""
Whether activity should cause the sandbox to resume when paused. Leave unset
to let the API pick the behavior. Set `False` to opt out explicitly and keep
auto-resume off even if the API's default changes. Can be `True` only when
`on_timeout` is `pause`. Not supported with `mode: "filesystem"` (a
filesystem-only snapshot must be resumed explicitly via `connect()`).
"""
class SandboxInfoLifecycle(TypedDict):
"""
Sandbox lifecycle configuration returned by sandbox info.
"""
on_timeout: Literal["pause", "kill"]
"""
What should happen to the sandbox when timeout is reached.
"""
auto_resume: bool
"""
Whether activity should cause the sandbox to resume when paused.
"""
def resolve_connect_memory(
on_resume: Optional["SandboxOnResume"],
) -> Union[Unset, bool]:
"""Resolve ``on_resume`` into ``ConnectSandboxV2.memory``.
``"restore"`` is the API's own default, so it travels as an omitted field.
"""
# A nullish value is not a choice of restore, matching how every other
# nullish option is treated. Any other value outside the union never reaches
# the API — it is resolved here into the boolean memory field — so it cannot
# be rejected server-side, and resolving it to restore would silently skip
# the reboot the caller asked for.
if on_resume is None:
return UNSET
allowed = ("restore", "reboot")
if on_resume not in allowed:
raise InvalidArgumentException(
f"on_resume must be one of: {', '.join(allowed)} (got {on_resume!r})."
)
return False if on_resume == "reboot" else UNSET
SandboxOnResume = Literal["restore", "reboot"]
"""
How a paused sandbox comes back.
``"restore"`` restores the memory snapshot, so processes and open connections
survive the pause. ``"reboot"`` ignores any memory in the snapshot and
cold-boots from disk state alone — the rescue path for a snapshot whose memory
image wedges the guest.
"""
def _resolve_network_selector(
selector: Optional[SandboxNetworkSelector],
rules: Mapping[str, List[SandboxNetworkRule]],
) -> Optional[List[str]]:
if selector is None:
return None
if callable(selector):
ctx = SandboxNetworkSelectorContext(all_traffic=ALL_TRAFFIC, rules=rules)
return list(selector(ctx))
return list(selector)
def _build_transform_context(
token_names: Iterable[str],
*,
validate: bool,
) -> SandboxNetworkTransformContext:
"""
Build the context handed to ``transform`` callables.
``token_names`` are the workload tokens the request registers; see
:class:`_IamTokenPlaceholders` for what ``validate`` controls.
"""
return SandboxNetworkTransformContext(
iam=_SandboxNetworkTransformIam(
tokens=IamTokenPlaceholders(token_names, validate=validate),
),
)
def _build_client_rules(
rules: SandboxNetworkRules,
ctx: SandboxNetworkTransformContext,
) -> SandboxNetworkConfigRules:
client_rules = SandboxNetworkConfigRules()
for host, host_rules in rules.items():
converted: List[ClientSandboxNetworkRule] = []
for rule in host_rules:
transform = rule.get("transform")
if transform is None:
converted.append(ClientSandboxNetworkRule())
continue
if callable(transform):
transform = transform(ctx)
# A callable that returns something other than a transform
# resolves to no headers at all, which would silently create the
# rule without the headers it is for.
if inspect.isawaitable(transform):
if inspect.iscoroutine(transform):
# Close it so the caller does not also get a
# "coroutine was never awaited" RuntimeWarning.
transform.close()
raise InvalidArgumentException(
f"Network transform callable for {host!r} must be "
"synchronous, it returned an awaitable. Resolve the "
"value before creating the sandbox."
)
if not isinstance(transform, Mapping):
raise InvalidArgumentException(
f"Network transform callable for {host!r} must return a "
f"transform dict, got {type(transform).__name__}."
)
client_transform = ClientSandboxNetworkTransform()
headers = transform.get("headers")
if headers:
client_headers = ClientSandboxNetworkTransformHeaders()
client_headers.additional_properties = dict(headers)
client_transform.headers = client_headers
converted.append(ClientSandboxNetworkRule(transform=client_transform))
client_rules.additional_properties[host] = converted
return client_rules
def _build_egress_proxy(
egress_proxy: SandboxEgressProxyOpts,
) -> ClientSandboxEgressProxyConfig:
"""
Rebuild the proxy config from the known fields so stray keys in the
caller's dict never reach the wire. Address reachability is the server's —
it is the only side that can tell whether the address resolves, and to where.
The required ``address`` key is checked here so an untyped caller that
omits it gets :class:`InvalidArgumentException` rather than a bare
``KeyError`` from deep inside create.
"""
# Re-check at runtime for callers that bypass the TypedDict — a bare
# KeyError from deep inside create would not name the option.
if not isinstance(egress_proxy, Mapping) or not isinstance(
egress_proxy.get("address"), str
):
raise InvalidArgumentException(
"network egress_proxy must be a dict with a string 'address' "
"(e.g. 'proxy.example.com:1080')."
)
# `is not None` also skips a ``None`` credential, which is what reading one
# out of an unset environment variable yields and what "this proxy takes no
# credentials" means; the API only accepts a string.
body = ClientSandboxEgressProxyConfig(address=egress_proxy["address"])
if egress_proxy.get("username") is not None:
body.username = egress_proxy["username"]
if egress_proxy.get("password") is not None:
body.password = egress_proxy["password"]
tls = egress_proxy.get("tls")
if tls is not None:
if isinstance(tls, bool):
if tls:
body.tls = ClientSandboxEgressProxyTLSConfig(enabled=True)
elif isinstance(tls, Mapping):
if "enabled" in tls:
raise InvalidArgumentException(
"network egress_proxy tls takes no 'enabled'; pass "
"tls=True or tls=False instead."
)
client_tls = ClientSandboxEgressProxyTLSConfig(enabled=True)
if tls.get("server_name") is not None:
client_tls.server_name = tls["server_name"]
if tls.get("ca_cert") is not None:
client_tls.ca_cert = tls["ca_cert"]
body.tls = client_tls
else:
raise InvalidArgumentException(
"network egress_proxy tls must be a bool or a dict."
)
return body
def _build_network_egress(
network: Mapping[str, Any],
ctx: SandboxNetworkTransformContext,
) -> Dict[str, Any]:
"""
Resolve the shared egress fields (``allow_out`` / ``deny_out`` /
``egress_proxy`` / per-host ``rules``) used by both the create and update
endpoints. ``rules`` in the returned dict is the inner
``Dict[host, List[ClientSandboxNetworkRule]]`` — callers wrap it in their
endpoint-specific rules attrs class.
"""
rules = network.get("rules") or {}
allow_out = _resolve_network_selector(network.get("allow_out"), rules)
deny_out = _resolve_network_selector(network.get("deny_out"), rules)
# `is not None` also covers an explicit `"egress_proxy": None`, which
# untyped callers spell "no proxy" as; the JS SDK's `!= null` does the
# same. Do not use truthiness — an empty dict must reach the builder so
# it fails loudly instead of silently disabling tunneling.
egress_proxy = network.get("egress_proxy")
body: Dict[str, Any] = {}
if allow_out is not None:
body["allow_out"] = allow_out
if deny_out is not None:
body["deny_out"] = deny_out
if egress_proxy is not None:
body["egress_proxy"] = _build_egress_proxy(egress_proxy)
# `is not None` so an empty list is sent (it means "no DNS server"), like
# the JS SDK's `!= null`.
if network.get("dns_servers") is not None:
body["dns_servers"] = list(network["dns_servers"])
if "rules" in network and network["rules"] is not None:
body["rules"] = _build_client_rules(network["rules"], ctx).additional_properties
return body
def build_network_config(
network: Optional[SandboxNetworkOpts],
iam: Optional[ClientSandboxIam] = None,
) -> Optional[Dict[str, Any]]:
"""Resolve a :class:`SandboxNetworkOpts` into the dict the API expects.
``iam`` is the built workload identity config of the same request — its
token names are what ``transform`` callables may reference.
"""
if network is None:
return None
token_names: List[str] = []
if iam is not None and not isinstance(iam.tokens, Unset):
token_names = iam.tokens.additional_keys
body = _build_network_egress(
network,
_build_transform_context(token_names, validate=True),
)
if "rules" in body:
client_rules = SandboxNetworkConfigRules()
client_rules.additional_properties = body["rules"]
body["rules"] = client_rules
if "allow_public_traffic" in network:
body["allow_public_traffic"] = network["allow_public_traffic"]
if "mask_request_host" in network:
body["mask_request_host"] = network["mask_request_host"]
if network.get("https_ports") is not None:
body["https_ports"] = list(network["https_ports"])
return body
def build_iam_config(
iam: Optional[SandboxIamOpts],
) -> Optional[ClientSandboxIam]:
"""Resolve a :class:`SandboxIamOpts` into the API client body.
Returns ``None`` for a config with no tokens — only a non-empty tokens
map enables workload identity, so an empty config is omitted from the
request payload entirely.
"""
if iam is None:
return None
tokens = iam.get("tokens")
if not tokens:
return None
client_tokens = ClientSandboxIamTokens()
for name, token in tokens.items():
# Re-check at runtime for callers that bypass the TypedDict — a bare
# KeyError from deep inside create would not name the option or the
# snake_case key the wire's camelCase 'tokenType' maps to.
if (
not isinstance(token, dict)
or not isinstance(token.get("audience"), str)
or not isinstance(token.get("token_type"), str)
):
raise InvalidArgumentException(
f"iam token {name!r} must be a dict with string 'audience' and "
"'token_type' values (snake_case 'token_type', not 'tokenType')."
)
# A network transform placeholder is the only way to consume a workload
# token, so a name that cannot appear in one is rejected where it is
# registered rather than at the reference that would have used it.
validate_iam_token_name(name)
client_tokens[name] = ClientSandboxIamToken(
audience=token["audience"],
token_type=token["token_type"],
)
body = ClientSandboxIam()
body.tokens = client_tokens
return body
@dataclass(frozen=True)
class SandboxLifecycleBody:
"""Lifecycle fields of a create-sandbox request, as ``NewSandboxV2`` takes them."""
auto_pause: Union[Unset, bool]
auto_pause_memory: Union[Unset, bool]
auto_resume: Union[Unset, ClientSandboxAutoResumeConfig]
def build_lifecycle_config(
lifecycle: Optional[SandboxLifecycle],
) -> SandboxLifecycleBody:
"""Resolve a :class:`SandboxLifecycle` into the create-request lifecycle fields.
``auto_pause`` is left unset when no ``on_timeout`` was configured: sending
``False`` would be indistinguishable from an explicit ``"kill"`` and would
override the default the API owns. ``auto_pause_memory`` is likewise left
unset unless the caller chose ``mode``.
"""
# on_timeout accepts a bare action or {"action", "mode"}; normalize.
# Only the object form carries mode (or the deprecated keep_memory).
on_timeout_raw = lifecycle.get("on_timeout") if lifecycle else None
# A missing on_timeout — or an explicit None from an untyped caller — is not
# a choice of kill. It only resolves to kill semantics locally, for the
# validation below.
on_timeout_configured = on_timeout_raw is not None
if isinstance(on_timeout_raw, dict):
on_timeout = on_timeout_raw.get("action")
pause_opts = cast(Dict[str, Any], on_timeout_raw)
else:
# Only fall back when unconfigured, not on other falsy-but-present
# values an untyped caller might pass.
on_timeout = on_timeout_raw if on_timeout_configured else "kill"
pause_opts = {}
allowed_actions = ("pause", "kill")
if on_timeout_configured and on_timeout not in allowed_actions:
# Name the field the caller wrote: the object form's bad value is on
# "action", not on on_timeout itself.
field = (
'on_timeout["action"]' if isinstance(on_timeout_raw, dict) else "on_timeout"
)
raise InvalidArgumentException(
f"{field} must be one of: {', '.join(allowed_actions)} (got {on_timeout!r})."
)
# The action never reaches the API — it is resolved here into the boolean
# auto_pause — so an unrecognized value cannot be rejected server-side, and
# resolving it to kill would delete the sandbox a caller asked to preserve.
# mode only governs a pause action. The discriminated union type forbids it
# on action="kill"; re-check at runtime for callers that bypass the type.
if ("mode" in pause_opts or "keep_memory" in pause_opts) and on_timeout != "pause":
raise InvalidArgumentException(
"mode is only allowed when on_timeout action is 'pause'."
)
memory = resolve_snapshot_memory(
'on_timeout["mode"]', pause_opts.get("mode"), pause_opts.get("keep_memory")
)
auto_resume = lifecycle.get("auto_resume") if lifecycle else None
if auto_resume and on_timeout != "pause":
raise InvalidArgumentException(
"auto_resume can only be True when on_timeout action is 'pause'."
)
if memory is False and auto_resume:
raise InvalidArgumentException(
"auto_resume: True is not a valid value with mode: 'filesystem' - "
"a filesystem-only snapshot cannot be auto-resumed by traffic and "
"must be resumed explicitly using Sandbox.connect()."
)
return SandboxLifecycleBody(
auto_pause=(on_timeout == "pause") if on_timeout_configured else UNSET,
auto_pause_memory=memory if on_timeout == "pause" else UNSET,
auto_resume=(
ClientSandboxAutoResumeConfig(enabled=auto_resume)
if auto_resume is not None
else UNSET
),
)
def build_network_update_body(
network: SandboxNetworkUpdate,
) -> SandboxNetworkUpdateConfig:
"""Resolve a :class:`SandboxNetworkUpdate` into the API client body."""
egress = _build_network_egress(
network, _build_transform_context([], validate=False)
)
body = SandboxNetworkUpdateConfig()
if "allow_out" in egress:
body.allow_out = egress["allow_out"]
if "deny_out" in egress:
body.deny_out = egress["deny_out"]
if "egress_proxy" in egress:
body.egress_proxy = egress["egress_proxy"]
if "dns_servers" in egress:
body.dns_servers = egress["dns_servers"]
if "rules" in egress:
rules = SandboxNetworkUpdateConfigRules()
rules.additional_properties = egress["rules"]
body.rules = rules
if "allow_internet_access" in network:
body.allow_internet_access = network["allow_internet_access"]
return body
def _from_client_egress_proxy(
egress_proxy: Union[ClientSandboxEgressProxyConfig, None, Unset],
) -> Optional[SandboxEgressProxyInfo]:
"""
Map the wire proxy config into the SDK-owned shape: ``password`` is dropped
because the API never returns it, and the wire's ``None`` for "no proxy"
becomes an absent key.
"""
if not isinstance(egress_proxy, ClientSandboxEgressProxyConfig):
return None
result: SandboxEgressProxyInfo = {"address": egress_proxy.address}
if not isinstance(egress_proxy.username, Unset):
result["username"] = egress_proxy.username
if (
isinstance(egress_proxy.tls, ClientSandboxEgressProxyTLSConfig)
and egress_proxy.tls.enabled is True
):
tls: SandboxEgressProxyTLSInfo = {}
if not isinstance(egress_proxy.tls.server_name, Unset):
tls["server_name"] = egress_proxy.tls.server_name
result["tls"] = tls
return result
def from_client_network_config(
network: Union[Unset, ClientSandboxNetworkConfig],
) -> Optional[SandboxNetworkInfo]:
if isinstance(network, Unset):
return None
result: SandboxNetworkInfo = {}
if not isinstance(network.allow_out, Unset):
result["allow_out"] = list(network.allow_out)
if not isinstance(network.deny_out, Unset):
result["deny_out"] = list(network.deny_out)
if not isinstance(network.rules, Unset):
result["rules"] = cast(
Dict[str, List[SandboxNetworkRuleInfo]], network.rules.to_dict()
)
egress_proxy = _from_client_egress_proxy(network.egress_proxy)
if egress_proxy is not None:
result["egress_proxy"] = egress_proxy
if not isinstance(network.dns_servers, Unset):
result["dns_servers"] = list(network.dns_servers)
if not isinstance(network.allow_public_traffic, Unset):
result["allow_public_traffic"] = network.allow_public_traffic
if not isinstance(network.mask_request_host, Unset):
result["mask_request_host"] = network.mask_request_host
if not isinstance(network.https_ports, Unset):
result["https_ports"] = list(network.https_ports)
return result
def from_client_lifecycle(
lifecycle: Union[Unset, ClientSandboxLifecycle],
) -> Optional[SandboxInfoLifecycle]:
if isinstance(lifecycle, Unset):
return None
result: SandboxInfoLifecycle = {
"on_timeout": cast(Literal["pause", "kill"], lifecycle.on_timeout),
"auto_resume": lifecycle.auto_resume,
}
return result
@dataclass
class SandboxInfo:
"""Information about a sandbox."""
sandbox_id: str
"""Sandbox ID."""
sandbox_domain: Optional[str]
"""Domain where the sandbox is hosted."""
template_id: str
"""Template ID."""
name: Optional[str]
"""Template name."""
metadata: Dict[str, str]
"""Saved sandbox metadata."""
started_at: datetime
"""Sandbox start time."""
end_at: datetime
"""Sandbox expiration date."""
state: SandboxState
"""Sandbox state."""
cpu_count: int
"""Sandbox CPU count."""
memory_mb: int
"""Sandbox Memory size in MiB."""
envd_version: str
"""Envd version."""
allow_internet_access: Optional[bool] = None
"""Whether internet access was explicitly enabled or disabled for the sandbox."""
network: Optional[SandboxNetworkInfo] = None
"""Sandbox network configuration."""
lifecycle: Optional[SandboxInfoLifecycle] = None
"""Sandbox lifecycle configuration."""
volume_mounts: List[Dict[str, str]] = field(default_factory=list)
"""Volume mounts for the sandbox."""
@classmethod
def _from_sandbox_data(
cls,
sandbox: Union[ListedSandbox, SandboxDetail],
sandbox_domain: Optional[str] = None,
allow_internet_access: Optional[bool] = None,
network: Optional[SandboxNetworkInfo] = None,
lifecycle: Optional[SandboxInfoLifecycle] = None,
):
return cls(
sandbox_domain=sandbox_domain,
sandbox_id=sandbox.sandbox_id,
template_id=sandbox.template_id,
name=(sandbox.alias if isinstance(sandbox.alias, str) else None),
metadata=cast(
Dict[str, str],
sandbox.metadata if isinstance(sandbox.metadata, dict) else {},
),
started_at=sandbox.started_at,
end_at=sandbox.end_at,
state=sandbox.state,
cpu_count=sandbox.cpu_count,
memory_mb=sandbox.memory_mb,
envd_version=sandbox.envd_version,
volume_mounts=[
{"name": vm.name, "path": vm.path} for vm in sandbox.volume_mounts
]
if not isinstance(sandbox.volume_mounts, Unset)
else [],
allow_internet_access=allow_internet_access,
network=network,
lifecycle=lifecycle,
)
@classmethod
def _from_listed_sandbox(cls, listed_sandbox: ListedSandbox):
return cls._from_sandbox_data(listed_sandbox)
@classmethod
def _from_sandbox_detail(cls, sandbox_detail: SandboxDetail):
return cls._from_sandbox_data(
sandbox_detail,
sandbox_domain=(
sandbox_detail.domain
if isinstance(sandbox_detail.domain, str)
else None
),
allow_internet_access=(
sandbox_detail.allow_internet_access
if isinstance(sandbox_detail.allow_internet_access, bool)
else None
),
network=from_client_network_config(sandbox_detail.network),
lifecycle=from_client_lifecycle(sandbox_detail.lifecycle),
)
SandboxListOrder = Literal["asc", "desc"]
"""Sort order for listing sandboxes by start time."""
@dataclass
class SandboxQuery:
"""Query parameters for listing sandboxes."""
metadata: Optional[dict[str, str]] = None
"""Filter sandboxes by metadata."""
state: Optional[list[SandboxState]] = None
"""Filter sandboxes by state."""
started_after: Optional[datetime] = None
"""Filter sandboxes to those started at or after this time. Naive datetimes are interpreted as local time."""
template: Optional[str] = None
"""Filter sandboxes by a template ID or name."""
@dataclass
class SandboxMetrics:
"""Sandbox metrics."""
cpu_count: int
"""Number of CPUs."""
cpu_used_pct: float
"""CPU usage percentage."""
disk_total: int
"""Total disk space in bytes."""
disk_used: int
"""Disk used in bytes."""
mem_total: int
"""Total memory in bytes."""
mem_used: int
"""Memory used in bytes."""
mem_cache: int
"""Cached memory (page cache) in bytes."""
timestamp: datetime
"""Timestamp of the metric entry."""
@dataclass
class SnapshotInfo:
"""Information about a snapshot."""
snapshot_id: str
"""Snapshot identifier — template ID with tag, or namespaced name with tag (e.g. my-snapshot:latest). Can be used with Sandbox.create() to create a new sandbox from this snapshot."""
names: List[str] = field(default_factory=list)
"""Full names of the snapshot template including project slug and tag (e.g. project-slug/my-snapshot:v2)."""
class SnapshotPaginatorBase(PaginatorBase[SnapshotInfo, ApiParams]):
def __init__(
self,
sandbox_id: Optional[str] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
name: Optional[str] = None,
**opts: Unpack[ApiParams],
):
super().__init__(limit=limit, next_token=next_token, **opts)
self.sandbox_id = sandbox_id
self.name = name
class SandboxPaginatorBase(PaginatorBase[SandboxInfo, ApiParams]):
def __init__(
self,
query: Optional[SandboxQuery] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
order: Optional[SandboxListOrder] = None,
**opts: Unpack[ApiParams],
):
super().__init__(limit=limit, next_token=next_token, **opts)
self.query = query
self.order = order