Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
import datetime
import logging
from typing import Any, Dict, List, Optional, Union, Unpack, cast
from packaging.version import Version
from e2b.api import (
SandboxCreateResponse,
api_exception_from_code,
encode_path_param,
handle_api_exception,
)
from e2b.api.client.api.sandboxes import (
delete_sandboxes_sandbox_id,
get_sandboxes_sandbox_id,
get_sandboxes_sandbox_id_metrics,
post_v2_sandboxes,
post_v_2_sandboxes_sandbox_id_connect,
post_sandboxes_sandbox_id_fork,
post_sandboxes_sandbox_id_pause,
post_sandboxes_sandbox_id_snapshots,
post_sandboxes_sandbox_id_timeout,
put_sandboxes_sandbox_id_network,
)
from e2b.api.client.api.templates import delete_templates_template_id
from e2b.api.client.models import (
ConnectSandboxV2,
Error,
NewSandboxV2,
SandboxSnapshotRequest,
SandboxTimeoutRequest,
SandboxForkRequest,
SandboxNetworkConfig,
SandboxPauseRequest,
SandboxVolumeMount as SandboxVolumeMountAPI,
)
from e2b.api.client.types import UNSET, Unset
from e2b.connection_config import ApiParams, ConnectionConfig
from e2b.exceptions import (
NotFoundException,
SandboxException,
SandboxNotFoundException,
TemplateException,
)
from e2b.sandbox.main import SandboxBase
from e2b.sandbox.sandbox_api import (
build_network_update_body,
McpServer,
SandboxIamOpts,
SandboxInfo,
SandboxLifecycle,
SandboxListOrder,
SandboxMetrics,
SandboxNetworkOpts,
SandboxNetworkUpdate,
SandboxOnResume,
SnapshotMode,
resolve_connect_memory,
resolve_snapshot_memory,
SandboxQuery,
SnapshotInfo,
build_iam_config,
build_lifecycle_config,
build_network_config,
to_sandbox_create_response,
validate_fork_count,
)
from e2b.sandbox_sync.paginator import SandboxPaginator, get_api_client
class SandboxApi(SandboxBase):
@classmethod
def list(
cls,
query: Optional[SandboxQuery] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
order: Optional[SandboxListOrder] = None,
**opts: Unpack[ApiParams],
) -> SandboxPaginator:
"""
List sandboxes.
By default (no `query.state` set), returns sandboxes in both `running`
and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`.
:param query: Filter the list of sandboxes by metadata, state, start time, or template, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])`
:param limit: Maximum number of sandboxes to return per page
:param next_token: Token for pagination
:param order: Sort order of the list of sandboxes by start time, applied across the whole result set before pagination (not within a page)
:return: A `SandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `paginator.next_items()` while `paginator.has_next` is True.
"""
return SandboxPaginator(
query=query,
limit=limit,
next_token=next_token,
order=order,
**cls._resolve_api_params(**opts),
)
@classmethod
def _cls_get_info(
cls,
sandbox_id: str,
**opts: Unpack[ApiParams],
) -> SandboxInfo:
"""
Get the sandbox info.
:param sandbox_id: Sandbox ID
:return: Sandbox info
"""
config = ConnectionConfig(**cls._resolve_api_params(**opts))
api_client = get_api_client(config)
res = get_sandboxes_sandbox_id.sync_detailed(
sandbox_id,
client=api_client,
)
if res.status_code == 404:
raise SandboxNotFoundException(f"Sandbox {sandbox_id} not found")
if res.status_code >= 300:
raise handle_api_exception(res)
if res.parsed is None:
raise Exception("Body of the request is None")
if isinstance(res.parsed, Error):
raise SandboxException(f"{res.parsed.message}: Request failed")
return SandboxInfo._from_sandbox_detail(res.parsed)
@classmethod
def _cls_kill(
cls,
sandbox_id: str,
**opts: Unpack[ApiParams],
) -> bool:
config = ConnectionConfig(**cls._resolve_api_params(**opts))
if config.debug:
# Skip killing the sandbox in debug mode
return True
api_client = get_api_client(config)
res = delete_sandboxes_sandbox_id.sync_detailed(
sandbox_id,
client=api_client,
)
if res.status_code == 404:
return False
if res.status_code >= 300:
raise handle_api_exception(res)
return True
@classmethod
def _cls_set_timeout(
cls,
sandbox_id: str,
timeout: int,
**opts: Unpack[ApiParams],
) -> None:
config = ConnectionConfig(**cls._resolve_api_params(**opts))
if config.debug:
# Skip setting timeout in debug mode
return
api_client = get_api_client(config)
res = post_sandboxes_sandbox_id_timeout.sync_detailed(
sandbox_id,
client=api_client,
body=SandboxTimeoutRequest(timeout=timeout),
)
if res.status_code == 404:
raise SandboxNotFoundException(f"Sandbox {sandbox_id} not found")
if res.status_code >= 300:
raise handle_api_exception(res)
@classmethod
def _cls_update_network(
cls,
sandbox_id: str,
network: SandboxNetworkUpdate,
**opts: Unpack[ApiParams],
) -> None:
config = ConnectionConfig(**cls._resolve_api_params(**opts))
api_client = get_api_client(config)
res = put_sandboxes_sandbox_id_network.sync_detailed(
sandbox_id,
client=api_client,
body=build_network_update_body(network),
)
if res.status_code == 404:
raise SandboxNotFoundException(f"Sandbox {sandbox_id} not found")
if res.status_code >= 300:
raise handle_api_exception(res)
@classmethod
def _create_sandbox(
cls,
template: str,
timeout: Optional[int],
allow_internet_access: Optional[bool],
metadata: Optional[Dict[str, str]],
env_vars: Optional[Dict[str, str]],
mcp: Optional[McpServer] = None,
network: Optional[SandboxNetworkOpts] = None,
iam: Optional[SandboxIamOpts] = None,
lifecycle: Optional[SandboxLifecycle] = None,
volume_mounts: Optional[List[SandboxVolumeMountAPI]] = None,
logger: Optional[logging.Logger] = None,
**opts: Unpack[ApiParams],
) -> SandboxCreateResponse:
params = cls._resolve_api_params(**opts)
config = ConnectionConfig(logger=logger, **params)
lifecycle_body = build_lifecycle_config(lifecycle)
# Built before the network config: ``transform`` callables are resolved
# against the workload tokens this request registers.
iam_body = build_iam_config(iam)
network_body = build_network_config(network, iam_body)
body = NewSandboxV2(
template_id=template,
auto_pause=lifecycle_body.auto_pause,
auto_pause_memory=lifecycle_body.auto_pause_memory,
auto_resume=lifecycle_body.auto_resume,
metadata=metadata or {},
timeout=timeout if timeout is not None else UNSET,
env_vars=env_vars or {},
mcp=cast(Any, mcp) or UNSET,
allow_internet_access=(
allow_internet_access if allow_internet_access is not None else UNSET
),
network=SandboxNetworkConfig(**network_body) if network_body else UNSET,
iam=iam_body or UNSET,
volume_mounts=volume_mounts if volume_mounts else UNSET,
)
api_client = get_api_client(config)
res = post_v2_sandboxes.sync_detailed(
body=body,
client=api_client,
)
if res.status_code >= 300:
raise handle_api_exception(res)
if res.parsed is None:
raise Exception("Body of the request is None")
if isinstance(res.parsed, Error):
raise SandboxException(f"{res.parsed.message}: Request failed")
if Version(res.parsed.envd_version) < Version("0.1.0"):
SandboxApi._cls_kill(res.parsed.sandbox_id, **params)
raise TemplateException(
"You need to update the template to use the new SDK."
)
return to_sandbox_create_response(res.parsed)
@classmethod
def _cls_get_metrics(
cls,
sandbox_id: str,
start: Optional[datetime.datetime] = None,
end: Optional[datetime.datetime] = None,
**opts: Unpack[ApiParams],
) -> List[SandboxMetrics]:
config = ConnectionConfig(**cls._resolve_api_params(**opts))
if config.debug:
# Skip getting the metrics in debug mode
return []
api_client = get_api_client(config)
res = get_sandboxes_sandbox_id_metrics.sync_detailed(
sandbox_id,
start=int(start.timestamp()) if start else UNSET,
end=int(end.timestamp()) if end else UNSET,
client=api_client,
)
if res.status_code == 404:
raise SandboxNotFoundException(f"Sandbox {sandbox_id} not found")
if res.status_code >= 300:
raise handle_api_exception(res)
if res.parsed is None:
return []
if isinstance(res.parsed, Error):
raise SandboxException(f"{res.parsed.message}: Request failed")
# Convert to typed SandboxMetrics objects
return [
SandboxMetrics(
cpu_count=metric.cpu_count,
cpu_used_pct=metric.cpu_used_pct,
disk_total=metric.disk_total,
disk_used=metric.disk_used,
mem_total=metric.mem_total,
mem_used=metric.mem_used,
mem_cache=metric.mem_cache,
timestamp=metric.timestamp,
)
for metric in res.parsed
]
@classmethod
def _cls_connect(
cls,
sandbox_id: str,
timeout: Optional[int] = None,
logger: Optional[logging.Logger] = None,
*,
on_resume: SandboxOnResume = "restore",
**opts: Unpack[ApiParams],
) -> SandboxCreateResponse:
config = ConnectionConfig(logger=logger, **cls._resolve_api_params(**opts))
api_client = get_api_client(config)
res = post_v_2_sandboxes_sandbox_id_connect.sync_detailed(
sandbox_id,
client=api_client,
body=ConnectSandboxV2(
timeout=timeout if timeout is not None else UNSET,
memory=resolve_connect_memory(on_resume),
),
)
if res.status_code == 404:
raise SandboxNotFoundException(f"Paused sandbox {sandbox_id} not found")
if res.status_code >= 300:
raise handle_api_exception(res)
if isinstance(res.parsed, Error):
raise SandboxException(f"{res.parsed.message}: Request failed")
if res.parsed is None:
raise Exception("Body of the request is None")
return to_sandbox_create_response(res.parsed)
@classmethod
def _cls_fork(
cls,
sandbox_id: str,
timeout: Optional[int] = None,
count: Optional[int] = None,
logger: Optional[logging.Logger] = None,
**opts: Unpack[ApiParams],
) -> List[Union[SandboxCreateResponse, Exception]]:
validate_fork_count(count)
config = ConnectionConfig(logger=logger, **cls._resolve_api_params(**opts))
api_client = get_api_client(config)
res = post_sandboxes_sandbox_id_fork.sync_detailed(
sandbox_id,
client=api_client,
body=SandboxForkRequest(
timeout=timeout if timeout is not None else UNSET,
count=count if count is not None else UNSET,
),
)
if res.status_code == 404:
message = (
res.parsed.message
if isinstance(res.parsed, Error)
else f"Sandbox {sandbox_id} not found"
)
raise SandboxNotFoundException(message)
if res.status_code >= 300:
raise handle_api_exception(res)
if isinstance(res.parsed, Error):
raise SandboxException(f"{res.parsed.message}: Request failed")
if res.parsed is None:
raise Exception("Body of the request is None")
results: List[Union[SandboxCreateResponse, Exception]] = []
for result in res.parsed:
sandbox = None if isinstance(result.sandbox, Unset) else result.sandbox
error = None if isinstance(result.error, Unset) else result.error
if error is not None or sandbox is None:
if error is None:
exception = SandboxException("Failed to start forked sandbox")
elif error.code == 404:
# 404 is call-site-specific in the SDK, so
# api_exception_from_code leaves it to the caller. A
# per-fork 404 refers to a resource needed to start that
# fork (e.g. the snapshot) — not the source sandbox, which
# would have failed the whole request — so stay generic.
exception = NotFoundException(f"{error.code}: {error.message}")
else:
exception = api_exception_from_code(error.code, error.message)
results.append(exception)
continue
results.append(to_sandbox_create_response(sandbox))
return results
@classmethod
def _cls_create_snapshot(
cls,
sandbox_id: str,
name: Optional[str] = None,
*,
mode: Optional[SnapshotMode] = None,
**opts: Unpack[ApiParams],
) -> SnapshotInfo:
config = ConnectionConfig(**cls._resolve_api_params(**opts))
api_client = get_api_client(config)
res = post_sandboxes_sandbox_id_snapshots.sync_detailed(
sandbox_id,
client=api_client,
body=SandboxSnapshotRequest(
name=name if name else UNSET,
memory=resolve_snapshot_memory("mode", mode),
),
)
if res.status_code == 404:
raise SandboxNotFoundException(f"Sandbox {sandbox_id} not found")
if res.status_code >= 300:
raise handle_api_exception(res)
if res.parsed is None:
raise Exception("Body of the request is None")
if isinstance(res.parsed, Error):
raise SandboxException(f"{res.parsed.message}: Request failed")
return SnapshotInfo(
snapshot_id=res.parsed.snapshot_id,
names=list(res.parsed.names) if res.parsed.names else [],
)
@classmethod
def _cls_delete_snapshot(
cls,
snapshot_id: str,
**opts: Unpack[ApiParams],
) -> bool:
config = ConnectionConfig(**cls._resolve_api_params(**opts))
api_client = get_api_client(config)
res = delete_templates_template_id.sync_detailed(
encode_path_param(snapshot_id),
client=api_client,
)
if res.status_code == 404:
return False
if res.status_code >= 300:
raise handle_api_exception(res)
return True
@classmethod
def _cls_pause(
cls,
sandbox_id: str,
keep_memory: Optional[bool] = None,
*,
mode: Optional[SnapshotMode] = None,
**opts: Unpack[ApiParams],
) -> bool:
config = ConnectionConfig(**cls._resolve_api_params(**opts))
api_client = get_api_client(config)
res = post_sandboxes_sandbox_id_pause.sync_detailed(
sandbox_id,
client=api_client,
body=SandboxPauseRequest(
memory=resolve_snapshot_memory("mode", mode, keep_memory)
),
)
if res.status_code == 404:
raise SandboxNotFoundException(f"Sandbox {sandbox_id} not found")
if res.status_code == 409:
# Sandbox is already paused
return False
if res.status_code >= 300:
raise handle_api_exception(res)
# Check if res.parse is Error
if isinstance(res.parsed, Error):
raise SandboxException(f"{res.parsed.message}: Request failed")
return True