Límites

Cuotas y límites de Lambda MicroVMs tal como los ve el SDK. Fuente: AWS_API_NOTES.md §2, §6 y §11 (medidos en la cuenta de desarrollo el 2026-09-15) y limits.json, del que se generan _limits.py (Python) y limits.ts (TypeScript), donde el SDK los valida en cliente.

Límite	Valor	Qué hace el SDK
Vida máxima de un sandbox (timeout, o max_lifetime)	28 800 s (8 h), running + suspended, no ajustable	SandboxLifetimeException por encima; el tope no se puede extender después
Regiones con Lambda MicroVMs	us-east-1, us-east-2, us-west-2, eu-west-1, eu-central-1, eu-north-1, ap-northeast-1, ap-south-1, ap-southeast-1, ap-southeast-2	rayito doctor avisa (WARN) fuera de ellas
Auto-suspensión (IdlePolicy.max_idle_seconds)	≥ 60 s y menor que timeout (o max_lifetime)	InvalidArgumentException si la pasas tú; sin idle, la de 300 s por defecto se desactiva si no cabe (60 s en modo pause)
Plazo lógico (timeout con max_lifetime/on_timeout)	≥ 1 s y como mucho max_lifetime − 60 s desde el arranque (max_lifetime 120–28 800 s, por defecto timeout + 60; 3600 en el shim)	set_timeout por encima del tope: InvalidArgumentException con el plazo intacto
Historial de métricas	una muestra cada 5 s mientras corre; anillo de 5 760 muestras (8 h), ≈ 350 KB por respuesta completa	max_points ≥ 1 reduce la serie
URLs de transferencia	3600 s por defecto, tope S3Staging.max_expires_in (86 400) y 604 800 s (7 días de SigV4)	InvalidArgumentException con use_signature_expiration <= 0
Ficheros por S3	desde threshold_bytes (8 MiB; mínimo 1 MiB); exportación multiparte desde 5 GiB, ≤ 1 000 partes de ≥ 8 MiB; PUT único ≤ 5 GiB	el SDK elige la ruta
Transferencias por sandbox	16 activas, 2 moviendo bytes a la vez, 64 terminadas retenidas 30 min	RateLimitException (RESOURCE_EXHAUSTED)
Metadatos por fichero	≤ 64 claves y ≤ 4 000 B en total (xattrs user.rayito.*)	InvalidArgumentException antes de llamar
Política de egress	≤ 256 entradas por lista, ≤ 64 nombres de host, ≤ 4 096 prefijos por familia tras restar	InvalidArgumentException
Persistencia (persist=S3Prefix(...))	prefijo de clave ≤ 900 bytes, ≤ 64 patrones en exclude; restauración automática con plazo de 600 s (persist_timeout / persistTimeoutMs)	InvalidArgumentException antes de llamar
runHookPayload (envs + metadata + hash del token)	4096 caracteres	InvalidArgumentException antes de llamar a AWS, nombrando envs y metadata
Conexiones concurrentes por MicroVM	8 (1 vCPU), 16, 32, 64, 128	≤ 2 canales HTTP/2 por sandbox: unarios y streams
Ancho de banda del endpoint	1 / 2 / 4 / 8 / 16 MB/s por tamaño	medido: 0,65 MB/s escritura, 6,71 MB/s lectura a 2 GB
list-microvms	50 items por página	pagina por dentro; list(metadata=) añade una sonda por sandbox
Procesos + PTYs vivos por sandbox	256 (impuesto por rayd)	RateLimitException (RESOURCE_EXHAUSTED)
Kernels (contextos de código) por sandbox	8 (impuesto por rayd)	RateLimitException
JWE del proxy	60 min	renovado a los 45 min por un hilo/task del SDK
create-microvm-auth-token	50 TPS	token bucket por proceso alineado con la cuota
run-microvm / resume / suspend / terminate	5 / 5 / 2 / 10 TPS	token bucket por proceso alineado con la cuota
get-microvm	100 TPS	token bucket por proceso
Conectores de red por run-microvm	10	InvalidArgumentException
envs de un comando	como variables de entorno del proceso	sin límite propio; el payload de creación sí
Salida retenida por proceso	64 × 32 KiB por suscriptor; output_truncated si nadie lee en 30 s	SandboxException("output_truncated: ...")
Tamaño de un result de run_code	> 12 MiB recortado a rayito/omitted	aparece en Result.extra
Salida guardada de un comando o PTY (desde 0.7.0)	64 MiB por descriptor (COMMAND_OUTPUT_MAX_BYTES); se conserva el final	truncated en el resultado; ajustable con max_output_bytes / maxOutputBytes (Comandos)
Volúmenes EFS por sandbox (desde 0.7.0, experimental)	de 1 a 4, y como mucho 4 entre mounts= y volumes=; exactamente un conector de egress propio (AWS_API_NOTES.md §16 Q131); ConfigureSandbox con plazo de 65 s	InvalidArgumentException antes de lanzar (Volúmenes EFS)
Access token propio (desde 0.7.0)	al menos 16 bytes decodificados (ACCESS_TOKEN_MIN_BYTES)	InvalidArgumentException
Agente de IA (AgentLimits, desde 0.8.0)	por defecto 50 pasos (max_steps), 1 000 000 tokens (max_total_tokens; None/null lo desactiva), 600 s (timeout_seconds / timeoutMs: 600_000) y 16 MiB de salida (max_output_bytes, como mucho 64 MiB)	AgentException con reason max_steps, token_budget o timeout (Errores)
Línea de evento del agente	≤ 4 MiB; una más larga se descarta y cuenta en dropped_lines	—
Memoria de una imagen de agente (AgentTemplate)	≥ 2048 MiB	InvalidArgumentException

Las cuotas TPS son por cuenta y región (AWS_API_NOTES.md §11); cuentas nuevas pueden empezar con valores menores.

Tamaño (CPU/RAM)

El tamaño (memoria y vCPU) es propiedad de la imagen (resources[0].minimumMemoryInMiB en create-microvm-image, AWS_API_NOTES.md §4). Es la misma forma que usa E2B: el tamaño se fija por build de template, con Template.build(cpu_count=, memory_mb=) (e2b template create --cpu-count --memory-mb).

Desde 0.6.0, Sandbox.create(size="4gb") (TypeScript: { size: "4gb" }) elige entre un catálogo cerrado de cinco tamaños (512mb, 1gb, 2gb, 4gb, 8gb): el SDK lo resuelve en el cliente, sin ninguna llamada a AWS, al nombre de la imagen de ese tamaño (rayito-base-4gb). Esa imagen tiene que estar publicada antes con rayito image publish --sizes 4gb; size= no cambia la memoria de una imagen ni de un sandbox en marcha. Sin size= se lanza la imagen de siempre. Ver Tamaños; Template.build(memory_mb=) construye además una imagen propia del tamaño que quieras (Templates).

Tabla de la documentación de AWS (AWS_API_NOTES.md §4; ancho de banda del endpoint, entrada + salida), con el coste de la hora en baseline derivado de los precios de §12 (AWS_API_NOTES.md §12 / Precios): nada de esta tabla salvo lo marcado está medido en una cuenta real.

minimumMemoryInMiB	baseline	pico (4x)	disco	ancho de banda	$/h en baseline
512	0.5 GB / 0.25 vCPU	2 GB / 1 vCPU	8 GB	1 MB/s	$0.0315
1024	1 GB / 0.5 vCPU	4 GB / 2 vCPU	8 GB	2 MB/s	$0.0631
2048 (default de rayito image publish)	2 GB / 1 vCPU	8 GB / 4 vCPU	8 GB	4 MB/s (medido 4.54 MB/s bajando 16 MiB, AWS_API_NOTES.md §7)	$0.1261
4096	4 GB / 2 vCPU	16 GB / 8 vCPU	16 GB	8 MB/s	$0.2522
8192	8 GB / 4 vCPU	32 GB / 16 vCPU	32 GB	16 MB/s	$0.5044

Lo único de esta tabla verificado en una cuenta real (AWS_API_NOTES.md §7 y Q68) es la fila de 2048: el ancho de banda medido (4.54 MB/s bajando 16 MiB) y lo que ve el guest (cpu_count=4, memory_mb=8016, el pico del rango, no el baseline). El resto de la tabla —baseline, pico, disco y ancho de banda de los otros cuatro tamaños— viene tal cual de la documentación de AWS, sin medir; el $/h es aritmética sobre esos números y los precios verificados de §12, no una factura observada. Otros valores de minimumMemoryInMiB fuera de esta tabla no están documentados ni medidos (RES-1): no los publiques sin medirlos tú mismo antes en tu cuenta.

Cómo elegir tamaño hoy: publica una imagen por tamaño, con un nombre que lo diga, y crea sandboxes contra esa imagen:

rayito image publish --artifact image/rayito-image.zip --base-image-version 1 \
    --bucket amzn-s3-demo-bucket --image-name myimg-4gb --memory-mib 4096

from rayito import Sandbox

with Sandbox.create("myimg-4gb") as sbx:
    print(sbx.get_info().memory_mb)

import { Sandbox } from "rayito";

await using sbx = await Sandbox.create({ template: "myimg-4gb" });

La CLI no valida --memory-mib contra la tabla de arriba (los valores no medidos podrían ser válidos igualmente): un valor fuera de lo verificado simplemente no tiene número de referencia aquí todavía.

Coste: mientras el sandbox está RUNNING, AWS factura por segundo al vCPU/GB de baseline de la columna de arriba (columna $/h en baseline, precios en Precios); si el sandbox consume por encima del baseline (hasta el pico 4x), ese exceso se factura aparte, a los vCPU/GB realmente consumidos (AWS_API_NOTES.md §12), no al precio del tamaño siguiente de la tabla. Cada versión de imagen publicada, sea cual sea su tamaño, cuesta además el storage del snapshot (mínimo 1 semana de retención, ver Precios e Imágenes e IAM).

Lo que ve el guest no es la línea base: SandboxInfo.cpu_count y SandboxInfo.memory_mb informan la vista del guest (nproc y MemTotal), no minimumMemoryInMiB. Con una imagen de 2048 MiB, get_info() midió cpu_count=4 y memory_mb=8016 — el pico del rango, no el baseline (AWS_API_NOTES.md Q68). Código que decide su paralelismo mirando nproc o la memoria total puede sobrepasar la línea base contratada — y, por el párrafo anterior, eso no es sólo una cuestión de rendimiento: ese exceso se paga a los vCPU/GB consumidos por encima del baseline, no sólo corre más rápido gratis.

Versionado y soporte

Rayito sigue SemVer 2.0.0 y publica tres componentes con la misma serie MAJOR.MINOR: el SDK de Python y el de TypeScript (rayito en PyPI y npm) y el agente rayd (asset firmado de la GitHub Release rayd-v* y binario dentro de la imagen). Cada uno tiene su changelog en formato Keep a Changelog (Changelog).

• Qué es la API pública: lo que exportan rayito y rayito.e2b (Python), rayito y rayito/e2b (TypeScript) sin guion bajo inicial, la CLI rayito, las herramientas de rayito-mcp y el contrato proto/rayito/v1/. Los módulos _privados, los tipos generados y los scripts del repositorio no lo son.
• Mientras sea 0.x (hoy, Development Status :: 3 - Alpha): una subida de MINOR puede romper compatibilidad y lo dice: commit feat!: o BREAKING CHANGE: y entrada en Changed o Removed del changelog. Un PATCH nunca rompe la API pública. Desde 1.0.0, sólo un MAJOR rompe.
• Obsolescencia: antes de retirar algo de la API pública se marca como obsoleto (DeprecationWarning en Python, @deprecated en TypeScript) y se anota en Deprecated del changelog al menos una MINOR antes de quitarlo. Las excepciones son que AWS retire la capacidad de la plataforma que lo sostiene o que lo exija una corrección de seguridad; las dos se explican en las notas de la release.
• Soporte: sólo la última línea MAJOR.MINOR recibe correcciones, de seguridad incluidas (SECURITY.md, "Versiones soportadas"). El SDK y la imagen deben ser de la misma serie: la tabla de abajo fija el rayd mínimo de cada SDK y rayito doctor la comprueba.
• Las versiones de imagen no son versiones de Rayito: rayito-base N.0 es un contador de builds que asigna AWS en cada cuenta (ver abajo).

Compatibilidad SDK ↔ rayd ↔ imagen

Los SDKs (Python y TypeScript) y rayd avanzan MAJOR.MINOR en lockstep (el patch puede divergir); cada fila fija el agent_version mínimo que trae las funciones que ese SDK usa. La versión de imagen (imageVersion) no es un criterio: es el contador de builds de cada imagen en cada cuenta (rayito-base 17.0, rayito-base-poly 3.0 y la primera imagen de una cuenta nueva, 1.0, llevan el mismo rayd), y agent_version sale del binario dentro de la imagen, así que ya prueba de qué tag se construyó. rayito doctor evalúa esta tabla en su comprobación compatibility (y muestra la versión de imagen sólo a título informativo) y rayito.cli._compat.COMPATIBILITY es la misma tabla en código: un test (tests/unit/cli/test_compat.py) impide que diverjan, y una release que suba un mínimo añade la fila en los dos sitios.

SDK	rayd mínimo	Nota
0.1	0.1.0	M6: imds_blocked, hook_anomalies y metadata exigen el rayd del tag rayd-v0.1.0
0.2	0.2.0	M7: Checkpoint/Restore (persist=) y language= exigen el rayd del tag rayd-v0.2.0
0.3	0.3.0	M9: max_lifetime/on_timeout, set_timeout, get_metrics_history, network= y los kernels Deno exigen el rayd del tag rayd-v0.3.0
0.4	0.4.0	0.4: UnimplementedError único, SetTimeout validado en el dominio y mensajes del agente en español exigen el rayd del tag rayd-v0.4.0
0.5	0.5.0	0.5: /suspend con sync acotado por sistema de ficheros y las funciones opcionales (secretos, índice, OTel) se validan con el rayd del tag rayd-v0.5.0
0.6	0.6.0	0.6: ConfigureSandbox y las funciones 0.6 (montajes S3, eventos, OTLP, pasarela de secretos, start/ready de templates) exigen el rayd del tag rayd-v0.6.0
0.7	0.7.0	0.7: los volúmenes EFS (create(volumes=)) y el endurecimiento del agente (hooks aislados, persistencia ligada al /run) exigen el rayd del tag rayd-v0.7.0
0.8	0.8.0	0.8: el agente de IA (sbx.agent, AgentTemplate y el warmup de los pools) se valida con el rayd del tag rayd-v0.8.0
0.9	0.9.0	0.9: connect() recupera sbx.gateways desde ConfigureStatus y el arranque rápido del agente sin la opción D se validan con el rayd del tag rayd-v0.9.0
0.10	0.10.0	0.10: el timeout y abort() del agente paran todo el árbol de procesos (kill_tree) y los proveedores del agente se validan con el rayd del tag rayd-v0.10.0