Shim E2B¶
rayito.e2b reexporta la API del SDK de E2B 2.x sobre Rayito. Cómo migrar:
Migrar desde E2B.
e2b
¶
Shim de compatibilidad con el SDK Python de E2B 2.x (contrato: e2b
2.51.0, e2b-code-interpreter 2.10.0).
Cambia la línea de import y el resto del programa sigue igual:
from e2b_code_interpreter import Sandbox -> from rayito.e2b import Sandbox
from e2b import AsyncSandbox, E2B -> from rayito.e2b import AsyncSandbox, E2B
from e2b.exceptions import ... -> from rayito.e2b.exceptions import ...
El plazo del sandbox (timeout, set_timeout, connect(timeout=),
lifecycle) lo impone rayd en una imagen 0.3.0 o posterior; upload_url/download_url
firman en S3; allow_internet_access=False y network son una política de
egress en el guest (rayito-base-caps); get_metrics(start, end) es el
historial del agente. Secret/AsyncSecret son CRUD sobre AWS Secrets
Manager en tu cuenta (fill devuelve el placeholder de E2B, que Rayito no
resuelve). Template/AsyncTemplate construyen imágenes de verdad, y
Volume/AsyncVolume y volume_mounts (experimental) funcionan con un
E2B(volume_store=...). Lo que Lambda MicroVMs no puede hacer (fork,
snapshots, MCP, iam, el contenido de un volumen fuera de un sandbox,
kernels que no sean python/bash/javascript/typescript...) lanza
UnimplementedError (un
NotImplementedError, nunca SandboxException) nombrando la feature y el
motivo. Los ApiParams sin sentido en AWS (api_key, domain, debug,
api_url, sandbox_url, validate_api_key, api_headers, secure=False)
avisan con RayitoCompatWarning y se ignoran. El rayito.Sandbox nativo
queda en sbx.native. Detalles: docs/site/docs/e2b-compat.md.
Los nombres de rayito.e2b que son las mismas clases que en rayito
(CommandHandle, AsyncCommandHandle, CommandResult, EntryInfo,
WriteEntry, FilesystemEvent, FilesystemEventType, FileType,
WatchHandle, AsyncWatchHandle, Execution, Result, Logs,
OutputMessage, ExecutionError, DownloadLink, UploadTicket,
ProcessInfo, Git y sus modelos, los gráficos, ALL_TRAFFIC,
SecretInfo y las excepciones nativas) se documentan en
Modelos, Subclientes y
Excepciones. Dos son alias con el nombre de E2B:
Context es CodeContext y WriteInfo es EntryInfo. Los alias de tipos
Username, Stdout, Stderr, MIMEType (str), PtyOutput (bytes),
RunCodeLanguage y OutputHandler existen sólo para que las anotaciones
de un programa de E2B sigan resolviendo.
Sandbox¶
Sandbox(template: str | None = None, timeout: int | None = None, metadata: Mapping[str, str] | None = None, envs: Mapping[str, str] | None = None, api_key: str | None = None, domain: str | None = None, debug: bool = False, sandbox_id: str | None = None, request_timeout: float | None = None, proxy: str | None = None, secure: bool = True, allow_internet_access: bool = True, *, lifecycle: Mapping[str, Any] | None = None, network: Mapping[str, Any] | None = None, max_lifetime: int | None = None, logger: logging.Logger | None = None, retries: int | None = None, headers: Mapping[str, str] | None = None, region: str | None = None, session: Any | None = None, template_version: str | None = None, execution_role_arn: str | None = None, allowed_ports: Sequence[PortLike] | None = None, ingress: Sequence[str] | None = None, logging: LoggingOption = 'disabled', access_token: str | None = None, ready_timeout: float = DEFAULT_READY_TIMEOUT_SECONDS, reconnect_timeout: float = DEFAULT_RECONNECT_TIMEOUT_SECONDS, keep_on_failure: bool = False, control_plane: Any | None = None, transport: Any | None = None, _native: NativeSandbox | None = None, _connection: ConnectionConfig | None = None)
¶
Drop-in de e2b_code_interpreter.Sandbox / e2b.Sandbox (2.51).
Constructor deprecado de E2B: crea el sandbox con la misma tabla
que create() o, con sandbox_id, se conecta (E2B v1). Los kwargs
de creación dados junto a sandbox_id avisan y no se aplican.
native: NativeSandbox
property
¶
El rayito.Sandbox de debajo (get_health, access_token, pty.create(shell=)...).
sandbox_domain: str
property
¶
El hostname del endpoint del MicroVM: el único dominio que tiene.
envd_api_url: str
property
¶
https://<endpoint>; toda petición necesita además get_host(8080).headers.
envd_direct_url: str
property
¶
Igual que envd_api_url: el endpoint es el único acceso directo.
traffic_access_token: str
property
¶
El JWE del proxy vigente para el puerto 8080 de rayd. Es una
credencial al portador del endpoint (rota a los 45 min, vive 60 como
mucho): nunca la loguees.
connection_config: ConnectionConfig
property
¶
La configuración efectiva: región, request_timeout, retries,
headers, proxy y logger dados al crear o conectar, y la
integración vigente entonces.
git: Git
property
¶
El rayito.Git nativo (comandos git con GIT_TERMINAL_PROMPT=0).
create(template: str | None = None, timeout: int | None = None, metadata: Mapping[str, str] | None = None, envs: Mapping[str, str] | None = None, secure: bool | None = None, allow_internet_access: bool | None = None, mcp: Any | None = None, network: Mapping[str, Any] | None = None, iam: Any | None = None, lifecycle: Mapping[str, Any] | None = None, volume_mounts: Any | None = None, logger: logging.Logger | None = None, *, max_lifetime: int | None = None, region: str | None = None, session: Any | None = None, template_version: str | None = None, execution_role_arn: str | None = None, allowed_ports: Sequence[PortLike] | None = None, ingress: Sequence[str] | None = None, logging: LoggingOption = 'disabled', access_token: str | None = None, ready_timeout: float = DEFAULT_READY_TIMEOUT_SECONDS, reconnect_timeout: float = DEFAULT_RECONNECT_TIMEOUT_SECONDS, keep_on_failure: bool = False, control_plane: Any | None = None, transport: Any | None = None, **api_params: Unpack[ApiParams]) -> Self
classmethod
¶
Sandbox.create(...) de E2B 2.x (tabla D5): timeout (300 s por
defecto) es el plazo lógico que impone rayd y max_lifetime la vida
de plataforma; lifecycle decide si al vencer se termina o se pausa;
allow_internet_access=False y network son la política de egress en
el guest (rayito-base-caps); mcp e iam son UnimplementedError,
y volume_mounts también salvo con un E2B(volume_store=...)
(experimental). headers, proxy y retries llegan al canal
y al plano; api_key, domain, debug, api_url, sandbox_url,
validate_api_key, api_headers y secure=False avisan con un
RayitoCompatWarning cada uno. Sobre una imagen anterior a 0.3.0 el VM
se termina y es UnimplementedError.
beta_create(template: str | None = None, timeout: int | None = None, auto_pause: bool = False, allow_internet_access: bool | None = None, metadata: Mapping[str, str] | None = None, envs: Mapping[str, str] | None = None, secure: bool | None = None, mcp: Any | None = None, network: Mapping[str, Any] | None = None, *, lifecycle: Mapping[str, Any] | None = None, logger: logging.Logger | None = None, max_lifetime: int | None = None, **kwargs: Any) -> Self
classmethod
¶
Sandbox.beta_create: como create, con auto_pause=True como
lifecycle={"on_timeout": "pause"} (sin auto-resume); network se
mapea igual que en create y mcp es UnimplementedError.
connect(timeout: int | None = None, *, on_resume: Literal['restore', 'reboot'] = 'restore', **api_params: Unpack[ApiParams]) -> Sandbox
¶
sbx.connect(): sobre el nativo ya enlazado hace get-microvm,
reanuda si estaba pausado, espera a Health y, con timeout,
extiende el plazo a al menos ahora + timeout. Devuelve self.
on_resume='reboot' es UnimplementedError.
list(query: SandboxQuery | None = None, limit: int | None = None, next_token: str | None = None, *, state: Sequence[SandboxState] | None = None, order: Literal['asc', 'desc'] | None = None, template: str | None = None, template_version: str | None = None, region: str | None = None, session: Any | None = None, control_plane: Any | None = None, transport: Any | None = None, index: DynamoDbIndex | None = None, **api_params: Unpack[ApiParams]) -> SandboxPaginator
classmethod
¶
SandboxPaginator sobre rayito.Sandbox.paginate: limit es el
tamaño de página y next_token reanuda un listado anterior. Con
query.metadata el filtro es O(n) sobre los sandboxes RUNNING (un
Health por sandbox, dentro de next_items()).
index=DynamoDbIndex(...) (extensión de Rayito; también
E2B(index=...)) resuelve query.metadata con la tabla opcional del
índice: admite state=[PAUSED] sin despertar ningún sandbox, pero sólo
encuentra los creados con rayito.Sandbox.create(index=...) o un
PoolConfig(index=...). Sin él, query.metadata con PAUSED sigue
siendo UnimplementedError.
Coste y activación¶
Activa: index= usa el índice de metadatos en DynamoDB.
Recursos y llamadas AWS: dynamodb:BatchGetItem por página de
list-microvms; ningún Health, token ni get-microvm.
Coste aproximado: 0,5 RRU por sandbox candidato ($0,125 por millón,
DynamoDB on-demand, us-east-1, consultado 2026-09-30).
IAM: dynamodb:BatchGetItem sobre la tabla (RayitoIndexReader).
Cómo apagarla: index=None (por defecto).
Ejemplo:
idx = DynamoDbIndex("rayito-sandboxes")
q = SandboxQuery(metadata={"user": "42"}, state=[SandboxState.PAUSED])
paused = Sandbox.list(query=q, index=idx).next_items()
is_running(request_timeout: float | None = None) -> bool
¶
Health con agent_ready, con la sonda acotada por request_timeout.
get_info(request_timeout: float | None = None) -> SandboxInfo
¶
SandboxInfo 2.x: get-microvm fresco, metadatos y hechos del
guest del último Health y, sobre un sandbox RUNNING, la política
de egress (GetNetwork) para network y allow_internet_access.
set_timeout(timeout: int, request_timeout: float | None = None) -> None
¶
Fija el plazo lógico en ahora + timeout segundos (SetTimeout
EXACT): puede alargarlo o acortarlo, con max_lifetime como tope.
get_metrics(start: datetime | None = None, end: datetime | None = None, request_timeout: float | None = None) -> builtins.list[SandboxMetrics]
¶
La serie de métricas en bytes y en orden (MetricsHistory, una
muestra cada 5 s). Sin rango y con el historial vacío o una imagen
anterior a 0.3.0 devuelve la instantánea de Metrics; con rango en una
imagen anterior a 0.3.0 es UnimplementedError.
pause(keep_memory: bool | None = None, **api_params: Unpack[ApiParams]) -> bool
¶
suspend-microvm y espera a SUSPENDED: True si lo pausó,
False si ya estaba SUSPENDING|SUSPENDED. keep_memory=False es
UnimplementedError (la pausa siempre guarda memoria y disco).
update_network(network: Mapping[str, Any] | None = None, request_timeout: float | None = None) -> None
¶
Sustituye la política de egress (allow_out, deny_out,
egress_proxy, allow_internet_access); rules es
UnimplementedError. Devuelve None, como E2B.
upload_url(path: str | None = None, user: str | None = None, use_signature: bool = False, use_signature_expiration: int | None = None) -> UploadTicket
¶
El UploadTicket nativo: un str con la URL, así que requests.put(url,
data=f, headers=url.headers) funciona y wait() espera la importación.
use_signature se ignora porque una URL de S3 siempre va firmada;
use_signature_expiration son los segundos de vida (<= 0 es
InvalidArgumentException); sin ruta no hay dónde importar el objeto.
download_url(path: str, user: str | None = None, use_signature: bool = False, use_signature_expiration: int | None = None) -> DownloadLink
¶
El DownloadLink nativo: una instantánea del fichero en S3 que vale
hasta que caduca la URL; use_signature se ignora como en upload_url.
get_host(port: int) -> HostAccess
¶
HostAccess nativo: un str con el hostname más .headers del proxy.
run_code(code: str, language: str | None = None, context: ContextLike | None = None, on_stdout: StdoutCallback | None = None, on_stderr: StdoutCallback | None = None, on_result: ResultCallback | None = None, on_error: ErrorCallback | None = None, envs: Mapping[str, str] | None = None, timeout: float | None = None, request_timeout: float | None = None) -> Execution
¶
run_code de E2B: language python, bash, javascript o
typescript (alias js/ts; None es Python) viaja al core, que
decide en el agente si la imagen lo tiene. bash, javascript y
typescript sólo existen en rayito-base-poly (javascript y typescript
con el kernel de Deno, que arranca en la primera celda); en otra
imagen el UNIMPLEMENTED del agente es UnimplementedError con la
excepción nativa como __cause__, y cualquier otro error nativo se
propaga tal cual. r, java y el resto son UnimplementedError sin
tocar el agente. timeout=None es el nativo de 300 s.
create_code_context(cwd: str | None = None, language: str | None = None, request_timeout: float | None = None) -> CodeContext
¶
create_code_context de E2B con el mismo contrato de language
que run_code: un kernel que la imagen no trae es
UnimplementedError desde el UNIMPLEMENTED del agente.
AsyncSandbox(*, _native: NativeAsyncSandbox, _connection: ConnectionConfig | None = None)
¶
Drop-in de e2b_code_interpreter.AsyncSandbox / e2b.AsyncSandbox (2.51).
envd_api_url: str
property
¶
https://<endpoint>; toda petición necesita además get_host(8080).headers.
traffic_access_token: str
property
¶
El JWE del proxy vigente para el puerto 8080 de rayd (credencial
al portador del endpoint, 60 min como mucho): nunca la loguees.
git: AsyncGit
property
¶
El rayito.AsyncGit nativo (E2B lo llama Git en ambos SDKs).
create(template: str | None = None, timeout: int | None = None, metadata: Mapping[str, str] | None = None, envs: Mapping[str, str] | None = None, secure: bool | None = None, allow_internet_access: bool | None = None, mcp: Any | None = None, network: Mapping[str, Any] | None = None, iam: Any | None = None, lifecycle: Mapping[str, Any] | None = None, volume_mounts: Any | None = None, logger: logging.Logger | None = None, *, max_lifetime: int | None = None, region: str | None = None, session: Any | None = None, template_version: str | None = None, execution_role_arn: str | None = None, allowed_ports: Sequence[PortLike] | None = None, ingress: Sequence[str] | None = None, logging: LoggingOption = 'disabled', access_token: str | None = None, ready_timeout: float = DEFAULT_READY_TIMEOUT_SECONDS, reconnect_timeout: float = DEFAULT_RECONNECT_TIMEOUT_SECONDS, keep_on_failure: bool = False, control_plane: Any | None = None, transport: Any | None = None, **api_params: Unpack[ApiParams]) -> Self
async
classmethod
¶
Misma tabla de kwargs que rayito.e2b.Sandbox.create.
beta_create(template: str | None = None, timeout: int | None = None, auto_pause: bool = False, allow_internet_access: bool | None = None, metadata: Mapping[str, str] | None = None, envs: Mapping[str, str] | None = None, secure: bool | None = None, mcp: Any | None = None, network: Mapping[str, Any] | None = None, *, lifecycle: Mapping[str, Any] | None = None, logger: logging.Logger | None = None, max_lifetime: int | None = None, **kwargs: Any) -> Self
async
classmethod
¶
Misma semántica que rayito.e2b.Sandbox.beta_create.
connect(timeout: int | None = None, *, on_resume: Literal['restore', 'reboot'] = 'restore', **api_params: Unpack[ApiParams]) -> AsyncSandbox
async
¶
Misma semántica que rayito.e2b.Sandbox.connect (instancia).
list(query: SandboxQuery | None = None, limit: int | None = None, next_token: str | None = None, *, state: Sequence[SandboxState] | None = None, order: Literal['asc', 'desc'] | None = None, template: str | None = None, template_version: str | None = None, region: str | None = None, session: Any | None = None, control_plane: Any | None = None, transport: Any | None = None, index: DynamoDbIndex | None = None, **api_params: Unpack[ApiParams]) -> AsyncSandboxPaginator
async
classmethod
¶
AsyncSandboxPaginator sobre rayito.AsyncSandbox.paginate; index=
(o E2B(index=...)) como en Sandbox.list: query.metadata sobre
sandboxes en pausa con dynamodb:BatchGetItem, sin sondas.
get_info(request_timeout: float | None = None) -> SandboxInfo
async
¶
Misma semántica que rayito.e2b.Sandbox.get_info.
set_timeout(timeout: int, request_timeout: float | None = None) -> None
async
¶
Misma semántica que rayito.e2b.Sandbox.set_timeout.
get_metrics(start: datetime | None = None, end: datetime | None = None, request_timeout: float | None = None) -> builtins.list[SandboxMetrics]
async
¶
Misma semántica que rayito.e2b.Sandbox.get_metrics.
pause(keep_memory: bool | None = None, **api_params: Unpack[ApiParams]) -> bool
async
¶
Misma semántica que rayito.e2b.Sandbox.pause.
update_network(network: Mapping[str, Any] | None = None, request_timeout: float | None = None) -> None
async
¶
Misma semántica que rayito.e2b.Sandbox.update_network.
upload_url(path: str | None = None, user: str | None = None, use_signature: bool = False, use_signature_expiration: int | None = None) -> AsyncUploadTicket
async
¶
Misma semántica que rayito.e2b.Sandbox.upload_url; es corrutina
porque armar la importación es una llamada al agente (divergencia
documentada: la de E2B es síncrona).
download_url(path: str, user: str | None = None, use_signature: bool = False, use_signature_expiration: int | None = None) -> DownloadLink
async
¶
Misma semántica que rayito.e2b.Sandbox.download_url.
run_code(code: str, language: str | None = None, context: ContextLike | None = None, on_stdout: StdoutCallback | None = None, on_stderr: StdoutCallback | None = None, on_result: ResultCallback | None = None, on_error: ErrorCallback | None = None, envs: Mapping[str, str] | None = None, timeout: float | None = None, request_timeout: float | None = None) -> Execution
async
¶
Mismo contrato de language que rayito.e2b.Sandbox.run_code.
create_code_context(cwd: str | None = None, language: str | None = None, request_timeout: float | None = None) -> CodeContext
async
¶
Mismo contrato de language que rayito.e2b.Sandbox.create_code_context.
SandboxInfo(sandbox_id: str, sandbox_domain: str | None, template_id: str, name: str | None, metadata: dict[str, str] | None, started_at: datetime, end_at: datetime | None, state: SandboxState, cpu_count: int | None, memory_mb: int | None, envd_version: str | None, allow_internet_access: bool | None = None, network: dict[str, list[str]] | None = None, lifecycle: dict[str, Any] | None = None, volume_mounts: list[dict[str, str]] = list(), raw_state: str = '')
dataclass
¶
SandboxInfo/ListedSandbox de E2B 2.x, con raw_state al final.
sandbox_domain es el endpoint (None en los items de list());
template_id es el ARN de la imagen y name su nombre; metadata es
None cuando no se leyó del agente; end_at es el plazo lógico vigente
(None en los items de list()); cpu_count, memory_mb y
envd_version (la versión de rayd) son None si no se leyeron del
agente. cpu_count/memory_mb (m15-sizes-catalog): si create(size=...)
se usó, el baseline declarado de la imagen (rayito.e2b._compat.
shim_cpu_memory), como E2B reporta lo declarado por el template; si no,
la vista real del guest vía Health, igual que antes de size=
(0.5.x). lifecycle es {"on_timeout", "auto_resume"} o None sin plazo
gestionado; network es {"allow_out", "deny_out"} o None si no se
leyó ninguna política; allow_internet_access es False sólo cuando la
política leída lo deniega todo; volume_mounts siempre está vacío.
state colapsa PENDING|RUNNING en RUNNING y SUSPENDING|SUSPENDED
en PAUSED; raw_state conserva el de AWS.
ListedSandbox es la misma clase que SandboxInfo, con el nombre que da
E2B a los elementos de Sandbox.list().
SandboxState
¶
Bases: StrEnum
Los dos estados que E2B expone; el de AWS queda en SandboxInfo.raw_state.
SandboxQuery(metadata: dict[str, str] | None = None, state: list[SandboxState] | None = None, started_after: datetime | None = None, template: str | None = None)
dataclass
¶
Filtro de Sandbox.list(query=...) en el orden de campos de E2B.
metadata es un subconjunto exacto (sólo sobre sandboxes RUNNING:
leerlo despertaría uno pausado); state los estados de E2B;
started_after "en o después"; template el nombre o ARN de la imagen.
SandboxMetrics(timestamp: datetime, cpu_used_pct: float, cpu_count: int, mem_used: int, mem_total: int, disk_used: int, disk_total: int, mem_cache: int = 0)
dataclass
¶
SandboxMetrics de E2B: una muestra en bytes. mem_cache es la page
cache (Cached de /proc/meminfo), 0 en un agente anterior a 0.3.0.
PtySize(rows: int = DEFAULT_PTY_ROWS, cols: int = DEFAULT_PTY_COLS)
dataclass
¶
PtySize(rows, cols) en el orden de campos de E2B; el nativo es (cols, rows).
SandboxPaginator(native: SandboxListPaginator, *, mapper: ItemMapper)
¶
SandboxPaginator de E2B sobre el paginador nativo de
Sandbox.paginate: has_next y next_token (opaco, reanudable con
Sandbox.list(next_token=...)) son los nativos y next_items() devuelve
SandboxInfo de E2B. Las sondas de metadatos de list(query=...)
ocurren dentro de next_items().
AsyncSandboxPaginator(native: AsyncSandboxListPaginator, *, mapper: ItemMapper)
¶
AsyncSandboxPaginator: el mismo contrato que SandboxPaginator
sobre el paginador nativo asíncrono.
Chart2D(*, type: ChartType, title: str | None = None, elements: list[Any] = list(), x_label: str | None = None, y_label: str | None = None, x_unit: str | None = None, y_unit: str | None = None)
dataclass
¶
Bases: Chart
Cliente y conexión¶
E2B(*, region: str | None = None, session: Any | None = None, control_plane: Any | None = None, index: DynamoDbIndex | None = None, bucket: str | None = None, volume_store: VolumeStore | None = None, volume_connector_arn: str | None = None, **api_params: Unpack[ApiParams])
¶
E2B(region=..., control_plane=..., headers=...): client.Sandbox y
client.AsyncSandbox usan esas opciones salvo que la llamada dé otras
(un None de la llamada cae al del cliente; headers de la llamada
sustituyen a las del cliente). Los ApiParams ignorados avisan una sola
vez, aquí. client.Secret/client.AsyncSecret usan su region y su
session (Secrets Manager en esa cuenta).
index=DynamoDbIndex(...) (extensión de Rayito, None por defecto) lo
usan client.Sandbox.list y client.AsyncSandbox.list cuando la
llamada no pasa otro: query.metadata sobre sandboxes en pausa con
dynamodb:BatchGetItem (ver rayito.DynamoDbIndex, "Coste y
activación"). Ninguna otra llamada lo usa.
client.Template/client.AsyncTemplate (m15-templates) usan su
region, su session y bucket= (extensión de Rayito: el bucket de
artefactos de Template.build, None por defecto; sin él cada
build debe pasar bucket=). client.Volume/client.AsyncVolume
(m15-efs-volumes, experimental) sólo funcionan con
volume_store=VolumeStore(...) — sin él, UnimplementedError; y
Sandbox.create(volume_mounts=...) necesita además
volume_connector_arn= (el ConnectorArn de la pila efs-volumes), que
sustituye a INTERNET_EGRESS como único conector de egress de ese
sandbox.
Volume: type[Volume]
property
¶
UnimplementedError("Volume") sin volume_store= en el
constructor; si no, una subclase de Volume ligada a él.
ConnectionConfig(*, request_timeout: float | None = None, retries: int | None = None, headers: Mapping[str, str] | None = None, proxy: str | None = None, logger: logging.Logger | None = None, region: str | None = None, **ignored: Any)
¶
e2b.ConnectionConfig: la configuración efectiva de un sandbox o una
construida a mano con las mismas reglas que create.
set_integration fija un nombre de integración de proceso que los
planos construidos después añaden al User-Agent de botocore; no
reconstruye los que ya existen (llámalo una vez al arrancar).
get_signature(*args: Any, **kwargs: Any) -> NoReturn
¶
e2b.get_signature: una firma de envd no sirve con el proxy de AWS.
Secretos¶
Secret
¶
e2b.Secret sobre AWS Secrets Manager (SecretStore). Los valores
son de sólo escritura: ninguna lectura los devuelve.
Coste y activación¶
Activa: llamar a Secret.create/update/get_info/list/exists/destroy es la
opción explícita; fill e importar el módulo no llaman a AWS.
Recursos y llamadas AWS: un secreto de Secrets Manager por create
(CreateSecret); DescribeSecret, PutSecretValue, UpdateSecret,
ListSecrets, DeleteSecret (AWS_API_NOTES.md §19).
Coste aproximado: $0,40 por secreto y mes hasta destroy + $0,05 por
10 000 llamadas (us-east-1, 2026-09-30).
IAM: la política RayitoSecretsAdmin de infra/secrets-access.yaml.
Cómo apagarla: no llames al CRUD; Secret.destroy(name) para dejar de pagar.
Ejemplo:
from rayito.e2b import Secret
info = Secret.create("openai-key", "sk-...", region="us-east-1")
Secret.fill("openai-key") # '${e2b.secrets.openai-key}' (no se resuelve)
Secret.destroy("openai-key")
create(name: str, value: str, metadata: dict[str, str] | None = None, **opts: Any) -> SecretInfo
classmethod
¶
Crea el secreto con su primer valor (versión 1).
update(secret: str, value: str, metadata: dict[str, str] | None = None, **opts: Any) -> SecretInfo
classmethod
¶
Guarda value como versión nueva; metadata sustituye la guardada.
get_info(secret: str, **opts: Any) -> SecretInfo
classmethod
¶
Metadatos del secreto (SecretNotFoundException si no existe).
list(limit: int | None = None, next_token: str | None = None, **opts: Any) -> SecretPaginator
classmethod
¶
Paginador sobre los secretos del prefijo.
exists(secret: str, **opts: Any) -> bool
classmethod
¶
True si el secreto existe.
destroy(secret: str, **opts: Any) -> bool
classmethod
¶
Lo borra sin ventana de recuperación: True si lo borró, False si no
existía (como E2B; ver SecretStore.destroy).
fill(secret: str) -> str
staticmethod
¶
${e2b.secrets.<name>} sin llamar a AWS. Rayito no lo resuelve.
iam_token(*, audience: str, token_type: str) -> NoReturn
staticmethod
¶
UnimplementedError: los MicroVMs no emiten tokens con audiencia.
AsyncSecret
¶
e2b.AsyncSecret: la misma semántica que Secret, con corrutinas
(boto3 en asyncio.to_thread). Los valores son de sólo escritura.
Coste y activación¶
Activa: llamar a AsyncSecret.create/update/get_info/list/exists/destroy
es la opción explícita; fill e importar el módulo no llaman a AWS.
Recursos y llamadas AWS: un secreto de Secrets Manager por create
(CreateSecret); DescribeSecret, PutSecretValue, UpdateSecret,
ListSecrets, DeleteSecret (AWS_API_NOTES.md §19).
Coste aproximado: $0,40 por secreto y mes hasta destroy + $0,05 por
10 000 llamadas (us-east-1, 2026-09-30).
IAM: la política RayitoSecretsAdmin de infra/secrets-access.yaml.
Cómo apagarla: no llames al CRUD; await AsyncSecret.destroy(name) para
dejar de pagar.
Ejemplo:
from rayito.e2b import AsyncSecret
info = await AsyncSecret.create("openai-key", "sk-...", region="us-east-1")
await AsyncSecret.destroy("openai-key")
destroy(secret: str, **opts: Any) -> bool
async
classmethod
¶
Lo borra sin ventana de recuperación: True si lo borró, False si no
existía (como E2B; ver SecretStore.destroy).
SecretPaginator(store: SecretStore, limit: int | None = None, next_token: str | None = None)
¶
Bases: _PaginatorState
e2b.SecretPaginator: while paginator.has_next: paginator.next_items().
next_items(**opts: Any) -> list[SecretInfo]
¶
La página siguiente (ListSecrets). Lanza si has_next es False.
AsyncSecretPaginator(store: SecretStore, limit: int | None = None, next_token: str | None = None)
¶
Bases: _PaginatorState
e2b.AsyncSecretPaginator: next_items es una corrutina.
next_items(**opts: Any) -> list[SecretInfo]
async
¶
La página siguiente (ListSecrets en asyncio.to_thread).
Templates¶
Template(spec: TemplateSpec | None = None)
¶
Bases: _TemplateTagStubs, Template
e2b.Template: el DSL de rayito.Template con la firma de build de
E2B.
AsyncTemplate(spec: TemplateSpec | None = None)
¶
Bases: _TemplateTagStubs, AsyncTemplate
e2b.AsyncTemplate: igual que Template, con las operaciones de
build en versión async (rayito.AsyncTemplate).
Volúmenes (experimental)¶
Volume(*, volume_id: str, access_point_id: str | None = None)
¶
AsyncVolume(*, volume_id: str, access_point_id: str | None = None)
¶
Bases: _VolumeBase
e2b.AsyncVolume: la misma semántica que Volume, con corrutinas
(el VolumeStore síncrono en un hilo). Sin volumen configurado, cada
classmethod lanza en el acto (nunca dentro de la corrutina que
devuelve): AsyncVolume.create(...) sin await ya lanzó, igual que el
Volume síncrono y que clients/typescript/src/e2b/volume.ts.
Excepciones¶
exceptions
¶
Excepciones con los nombres de e2b.exceptions (E2B 2.51).
Las nativas se re-exportan tal cual (son las mismas clases, no copias),
UnimplementedError incluida: un except rayito.UnimplementedError atrapa
lo que lanza el shim y un except rayito.e2b.UnimplementedError lo que
lanza el SDK nativo. El shim la construye con doc=COMPAT_DOC_PATH.
NotEnoughSpaceException y ServiceBusyException son alias de las clases
que Rayito sí lanza (DiskFullException, CapacityException).
TemplateException y BuildException también son las nativas: lo que lanza
Template.build() (nativo o del shim) lo atrapan por igual
except rayito.BuildException y except rayito.e2b.BuildException. A
diferencia de E2B, las dos son SandboxException. SecretException y SecretNotFoundException
son las nativas (las lanza el Secret/AsyncSecret del shim); a diferencia
de E2B, SecretException es un SandboxException y
SecretNotFoundException también es la NotFoundException nativa.
RayitoCompatWarning vive en rayito.exceptions y se re-exporta aquí.
Divergencia documentada: en E2B FileUploadException hereda de
BuildException porque sólo sale de construir templates; en Rayito hereda
de TransferException (un SandboxException) porque sólo sale de una
importación de upload_url/escritura grande que termina FAILED.
AuthenticationException(message: str, *, proxy_rejected: bool = False, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: Exception
Credenciales o token rechazados por AWS, por el proxy o por el agente.
proxy_rejected es True sólo cuando el 403 vino del proxy de AWS (JWE
ausente, expirado o sin el puerto): el SDK reacuña y reintenta una vez.
BuildException(message: str, *, reason: str | None = None, step: int | None = None, command: str | None = None, exit_code: int | None = None, log_tail: str | None = None)
¶
Bases: SandboxException
Template.build (m15-templates) falló: reason nombra la causa
(build_quota, aws_error cuando AWS rechazó el build por otro motivo
—el mensaje y __cause__ llevan sólo el resumen saneado—,
ready_client_error, ready_server_error, o None con
step/command/exit_code/log_tail cuando falló un paso del
Dockerfile compilado).
CommandExitException(message: str, *, exit_code: int, stdout: str = '', stderr: str = '', error: str | None = None, grpc_code: grpc.StatusCode | None = None, truncated: bool = False)
¶
Bases: SandboxException
Un comando terminó con exit code distinto de cero. truncated es
True cuando stdout o stderr superaron max_output_bytes y sólo
conservan su final.
FileNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
FileUploadException(message: str, *, code: str, reason: str, grpc_code: grpc.StatusCode | None = None)
¶
Bases: TransferException
La importación de un UploadTicket o de una escritura grande terminó
FAILED o CANCELLED con un code sin excepción propia (el nombre de
E2B para una subida fallida).
GitAuthException(message: str, *, proxy_rejected: bool = False, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: AuthenticationException
Un comando git del módulo sandbox.git falló por credenciales: el
remoto pidió usuario y contraseña (GIT_TERMINAL_PROMPT=0 no deja
preguntar) o los rechazó. El mensaje nombra la acción de git y nunca
contiene la URL ni las credenciales.
GitUpstreamException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
git push/git pull sin rama remota configurada: el mensaje explica
cómo fijarla (set_upstream=True o remote/branch explícitos).
InvalidArgumentException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
Un argumento inválido, detectado por el SDK antes de llamar a nadie,
por el agente (INVALID_ARGUMENT, FAILED_PRECONDITION) o por la API de
AWS (ValidationException). El mensaje nombra el argumento.
NotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
Lo pedido no existe: un proceso, un contexto de código o un
checkpoint (NOT_FOUND, OUT_OF_RANGE del agente).
RateLimitException(message: str, *, retry_after: float | None = None, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
Límite de tasa o de recursos: RESOURCE_EXHAUSTED del agente
(procesos, PTYs, contextos o transferencias simultáneas) o
ThrottlingException de AWS. retry_after son los segundos que AWS
sugiere esperar, si los dio.
RayitoCompatWarning
¶
Bases: UserWarning
Aviso de compatibilidad: un kwarg de E2B que Rayito ignora
(api_key, domain, debug, api_url, sandbox_url,
validate_api_key, api_headers, secure=False), o la primera vez que
un proceso usa secrets= (fase 1: el valor inyectado es visible para el
código del sandbox). El aviso nombra el kwarg, nunca su valor.
SandboxException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: Exception
Error atribuible a un sandbox.
status_code es el HTTP del plano de control, grpc_code el status del
agente y aws_code el nombre de la excepción de botocore; los tres son
opcionales según el origen.
SandboxNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: NotFoundException
El sandbox no existe o ya terminó (ResourceNotFoundException del
plano de control, o un MicroVM terminado al reconectar).
SecretException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
Error de un secreto de Secrets Manager (SecretStore, SecretCache,
secrets=, y el Secret/AsyncSecret del shim de E2B). El mensaje
nunca contiene el valor ni el nombre del secreto (los nombres son
selectores confidenciales, como en E2B); con secrets= nombra la clave
de la variable de entorno. aws_code es el Code de AWS, si lo hubo.
Divergencia con E2B: allí SecretException hereda de Exception; aquí
de SandboxException, para que un except SandboxException de Rayito
también la atrape.
SecretNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SecretException, NotFoundException
El secreto no existe o está programado para borrarse. También es la
NotFoundException nativa. Nunca se guarda en SecretCache.
TemplateException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
Template (m15-templates): un nombre o un tag inválido, o una
imagen anterior a 0.6 pasada a Sandbox.create() con un Template.
TimeoutException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
Venció un plazo: el timeout de un comando o de run_code, el de una
llamada (DEADLINE_EXCEEDED) o el plazo del propio sandbox
(sandbox_timeout de rayd).
UnimplementedError(feature: str, reason: str, doc: str | None = None)
¶
Bases: NotImplementedError
Una feature que este sandbox no puede ofrecer: falta configuración
(upload_url sin transfer=S3Staging(...)), la imagen corre un rayd
anterior o AWS no tiene la primitiva.
No es SandboxException a propósito, como NotImplementedError: un
except SandboxException no debe tragarse una feature ausente.
feature y reason describen qué falta y por qué; doc es la página
que lo explica (el shim de E2B pasa la de compatibilidad). El mensaje
nunca contiene datos del usuario.
VolumeException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
Error de un volumen EFS (m15-efs-volumes, experimental):
VolumeStore.create/get/list/destroy o el estado de volumes= tras
/run.
VolumeNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: VolumeException
El volumen no existe: VolumeStore.get/destroy sobre un nombre sin
AccessPoint, o el access point o el sistema de ficheros ya no están.
VolumePathNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: VolumeException
Reservada con el nombre de E2B: esta versión no la lanza. Las
operaciones de contenido de un volumen (read_file/write_file/... del
shim de E2B) no tienen plano de datos propio fuera de un sandbox y son
UnimplementedError.