---

Resumen

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

• Ejecución aislada: Cada tarea se ejecuta aislada del sistema anfitrión
• Límites de recursos: Establece límites de CPU, memoria y tiempo de espera por tarea
• Reintentos automáticos: Maneja fallos sin intervención manual
• Seguimiento del ciclo de vida: Monitorea 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:
    """Procesa datos en un entorno aislado y con control de recursos."""
    # Tu código se ejecuta de forma segura en un sandbox Wasm
    return {"processed": len(dataset), "status": "complete"}

Con TypeScript / JavaScript

Usa la función envolvente 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 => {
  // Tu código se ejecuta de forma segura en un sandbox Wasm
  return { processed: dataset.length, status: "complete" };
});

[!NOTA] 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 WebAssembly y se ejecuta en sandboxes aislados.

Cada tarea opera dentro de su propio sandbox con límites de recursos configurables, garantizando que los fallos estén contenidos y no se propaguen a otras partes de tu flujo de trabajo. El sistema anfitrión controla todos los aspectos de la ejecución, desde la asignación de CPU mediante el medidor de combustible de Wasm hasta las restricciones de memoria y la aplicación del tiempo 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 "¡Hola desde 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 "¡Hola desde Capsule!";
});

Ejecútalo:

capsule run hello.ts

[!CONSEJO] Agrega --verbose para ver detalles en tiempo real de la ejecución de la tarea.

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=["código a ejecutar"]
)

Crea sandbox.py:

from capsule import task

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

TypeScript / JavaScript

[!IMPORTANTE] Necesitas @capsule-run/cli en tus dependencias para usar las funciones de ejecutor en TypeScript.

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

const result = await run({
  file: './sandbox.ts',
  args: ['código a ejecutar']
});

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);
});

[!CONSEJO] 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	Valor por defecto	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 combustible de WebAssembly, que mide la ejecución de instrucciones. El nivel de cómputo determina cuánto combustible 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 combustible para operaciones intensivas en cómputo
• CUSTOM para especificar un valor exacto de combustible (p. ej., compute="1000000") para 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": "¡Hola desde 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ó con éxito
• 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 reintentos realizados
  • fuel_consumed — Recursos de CPU utilizados (ver Niveles de cómputo)
  • ram_used — Pico de memoria usada en bytes
  • host_requests — Lista de solicitudes al anfitrión realizadas por la tarea

Acceso a la red