capsule

---

Capsule es un runtime para ejecutar código no confiable en entornos aislados. Cada tarea se ejecuta dentro de su propio sandbox de WebAssembly, lo que proporciona:

• Ejecución aislada: Cada tarea se ejecuta aislada de tu sistema anfitrión
• Límites de recursos: Establece límites de CPU, memoria y tiempo de espera por tarea
• Reintentos automáticos: Gestiona fallos sin intervención manual
• Seguimiento del ciclo de vida: Supervisa qué tareas están en ejecución, completadas o fallidas

Cómo funciona

Con Python

Simplemente anota tus funciones de Python con el decorador @task:

from capsule import task

@task(name="analyze_data", compute="MEDIUM", ram="512MB", timeout="30s", max_retries=1)
def analyze_data(dataset: list) -> dict:
    """Process data in an isolated, resource-controlled environment."""
    # Your code runs safely in a Wasm sandbox
    return {"processed": len(dataset), "status": "complete"}

Con TypeScript / JavaScript

Usa la función envoltorio task() con acceso completo al ecosistema npm:

import { task } from "@capsule-run/sdk";

export const analyzeData = task({
  name: "analyze_data",
  compute: "MEDIUM",
  ram: "512MB",
  timeout: "30s",
  maxRetries: 1
}, (dataset: number[]): object => {
  // Your code runs safely in a Wasm sandbox
  return { processed: dataset.length, status: "complete" };
});

[!NOTE] El runtime requiere una tarea llamada "main" como punto de entrada. Python creará una automáticamente si no se define ninguna, pero se recomienda establecerla explícitamente.

Cuando ejecutas capsule run main.py (o main.ts), tu código se compila en un módulo de WebAssembly y se ejecuta en sandboxes aislados.

Cada tarea opera dentro de su propio sandbox con límites de recursos configurables, lo que garantiza que los fallos queden contenidos y no se propaguen en cascada a otras partes de tu flujo de trabajo. El sistema anfitrión controla cada aspecto de la ejecución, desde la asignación de CPU mediante la medición de fuel de Wasm hasta las restricciones de memoria y la aplicación de tiempos de espera.

Primeros pasos

Python

pip install capsule-run

Crea hello.py:

from capsule import task

@task(name="main", compute="LOW", ram="64MB")
def main() -> str:
    return "Hello from Capsule!"

Ejecútalo:

capsule run hello.py

TypeScript / JavaScript

npm install -g @capsule-run/cli
npm install @capsule-run/sdk

Crea hello.ts:

import { task } from "@capsule-run/sdk";

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (): string => {
  return "Hello from Capsule!";
});

Ejecútalo:

capsule run hello.ts

[!TIP] Añade --verbose para ver los detalles de ejecución de las tareas en tiempo real.

Ejecutar desde tu código

La función run() te permite ejecutar tareas programáticamente desde tu código en lugar de usar la CLI. Los args se reenvían automáticamente como parámetros a la tarea main.

Python

from capsule import run

result = await run(
    file="./sandbox.py",
    args=["code to execute"]
)

Crea sandbox.py:

from capsule import task

@task(name="main", compute="LOW", ram="64MB")
def main(code: str) -> str:
    return eval(code)

TypeScript / JavaScript

[!IMPORTANT] Necesitas @capsule-run/cli en tus dependencias para usar las funciones del runner en TypeScript.

import { run } from '@capsule-run/sdk/runner';

const result = await run({
  file: './sandbox.ts',
  args: ['code to execute']
});

Crea sandbox.ts:

import { task } from "@capsule-run/sdk";

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (code: string): string => {
  return eval(code);
});

[!TIP] Si buscas una solución preconfigurada y lista para usar, consulta el adaptador de Python o el adaptador de TypeScript.

Documentación

Opciones de configuración de tareas

Configura tus tareas con estos parámetros:

Parámetro	Descripción	Tipo	Predeterminado	Ejemplo
name	Identificador de la tarea	str	nombre de la función (Python) / obligatorio (TS)	"process_data"
compute	Nivel de asignación de CPU: "LOW", "MEDIUM" o "HIGH"	str	"MEDIUM"	"HIGH"
ram	Límite de memoria para la tarea	str	ilimitado	"512MB", "2GB"
timeout	Tiempo máximo de ejecución	str	ilimitado	"30s", "5m", "1h"
max_retries / maxRetries	Número de intentos de reintento en caso de fallo	int	0	3
allowed_files / allowedFiles	Carpetas accesibles en el sandbox (con modo de acceso opcional)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	Dominios accesibles en el sandbox	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	Variables de entorno accesibles en el sandbox	list	[]	["API_KEY"]

Niveles de cómputo

Capsule controla el uso de CPU mediante el mecanismo de fuel de WebAssembly, que mide la ejecución de instrucciones. El nivel de cómputo determina cuánto fuel recibe tu tarea.

• LOW proporciona una asignación mínima para tareas ligeras
• MEDIUM ofrece recursos equilibrados para cargas de trabajo típicas
• HIGH otorga el máximo fuel para operaciones intensivas en cómputo
• CUSTOM para especificar un valor de fuel exacto (por ejemplo, compute="1000000") y tener un control preciso sobre los límites de ejecución.

Formato de respuesta

Cada tarea devuelve un sobre JSON estructurado que contiene tanto el resultado como los metadatos de ejecución:

{
  "success": true,
  "result": "Hello from Capsule!",
  "error": null,
  "execution": {
    "task_name": "data_processor",
    "duration_ms": 1523,
    "retries": 0,
    "fuel_consumed": 45000,
    "ram_used": 1200000,
    "host_requests": [{...}]
  }
}

Campos de la respuesta:

• success — Booleano que indica si la tarea se completó correctamente
• result — El valor de retorno real de tu tarea (json, string, null en caso de fallo, etc.)
• error — Detalles del error si la tarea falló ({ error_type: string, message: string })
• execution — Métricas de rendimiento:
  • task_name — Nombre de la tarea ejecutada
  • duration_ms — Tiempo de ejecución en milisegundos
  • retries — Número de intentos de reintento que se produjeron
  • fuel_consumed — Recursos de CPU utilizados (consulta Niveles de cómputo)
  • ram_used — Memoria máxima utilizada en bytes
  • host_requests — Lista de solicitudes al host realizadas por la tarea

Acceso a la red

Las tareas pueden realizar solicitudes HTTP a los dominios especificados en allowed_hosts. Por defecto, no se permite ninguna solicitud saliente ([]). Proporciona una lista de dominios permitidos para conceder acceso, o usa ["*"] para permitir todos los dominios.

Python