---

Panoramica

Capsule è un runtime per eseguire codice non fidato in ambienti isolati. Ogni task viene eseguito all'interno del proprio sandbox WebAssembly, fornendo:

• Esecuzione isolata: Ogni task viene eseguito in modo isolato dal sistema host
• Limiti di risorse: Imposta limiti di CPU, memoria e timeout per ogni task
• Retry automatici: Gestisce i fallimenti senza intervento manuale
• Monitoraggio del ciclo di vita: Tieni traccia di quali task sono in esecuzione, completati o falliti

Come Funziona

Con Python

Basta annotare le funzioni Python con il decoratore @task:

from capsule import task

@task(name="analyze_data", compute="MEDIUM", ram="512MB", timeout="30s", max_retries=1)
def analyze_data(dataset: list) -> dict:
    """Elabora i dati in un ambiente isolato e con controllo delle risorse."""
    # Il tuo codice viene eseguito in modo sicuro in un sandbox Wasm
    return {"processed": len(dataset), "status": "complete"}

Con TypeScript / JavaScript

Usa la funzione wrapper task() con accesso completo all'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 => {
  // Il tuo codice viene eseguito in modo sicuro in un sandbox Wasm
  return { processed: dataset.length, status: "complete" };
});

[!NOTE] Il runtime richiede un task chiamato "main" come punto di ingresso. Python ne creerà automaticamente uno se non ne viene definito, ma si consiglia di impostarlo esplicitamente.

Quando esegui capsule run main.py (o main.ts), il tuo codice viene compilato in un modulo WebAssembly ed eseguito in sandbox isolati.

Ogni task opera all'interno del proprio sandbox con limiti di risorse configurabili, garantendo che i fallimenti siano contenuti e non si propaghino ad altre parti del tuo flusso di lavoro. Il sistema host controlla ogni aspetto dell'esecuzione, dall'allocazione della CPU tramite la misurazione del carburante Wasm ai vincoli di memoria e all'applicazione dei timeout.

Per Iniziare

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!"

Eseguilo:

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

Eseguilo:

capsule run hello.ts

[!TIP] Aggiungi --verbose per vedere i dettagli dell'esecuzione del task in tempo reale.

Esegui dal Tuo Codice

La funzione run() ti consente di eseguire task in modo programmatico dal tuo codice invece di usare la CLI. Gli args vengono automaticamente inoltrati come parametri al task main.

Python

from capsule import run

result = await run(
    file="./sandbox.py",
    args=["codice da eseguire"]
)

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] Devi avere @capsule-run/cli nelle tue dipendenze per usare le funzioni runner in TypeScript.

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

const result = await run({
  file: './sandbox.ts',
  args: ['codice da eseguire']
});

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] Se stai cercando una soluzione preconfigurata e pronta all'uso, dai un'occhiata all'adattatore Python o all'adattatore TypeScript.

Documentazione

Opzioni di Configurazione dei Task

Configura i tuoi task con questi parametri:

Parametro	Descrizione	Tipo	Default	Esempio
name	Identificatore del task	str	nome della funzione (Python) / richiesto (TS)	"process_data"
compute	Livello di allocazione CPU: "LOW", "MEDIUM" o "HIGH"	str	"MEDIUM"	"HIGH"
ram	Limite di memoria per il task	str	illimitato	"512MB", "2GB"
timeout	Tempo massimo di esecuzione	str	illimitato	"30s", "5m", "1h"
max_retries / maxRetries	Numero di tentativi di ripetizione in caso di fallimento	int	0	3
allowed_files / allowedFiles	Cartelle accessibili all'interno del sandbox (con modalità di accesso opzionale)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	Domini accessibili all'interno del sandbox	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	Variabili d'ambiente accessibili all'interno del sandbox	list	[]	["API_KEY"]

Livelli di Compute

Capsule controlla l'uso della CPU tramite il meccanismo del carburante di WebAssembly, che misura l'esecuzione delle istruzioni. Il livello di compute determina quanto carburante riceve il tuo task.

• LOW fornisce un'allocazione minima per task leggeri
• MEDIUM offre risorse bilanciate per carichi di lavoro tipici
• HIGH garantisce il massimo carburante per operazioni ad alta intensità di calcolo
• CUSTOM per specificare un valore esatto di carburante (es. compute="1000000") per un controllo preciso sui limiti di esecuzione.

Formato della Risposta

Ogni task restituisce un involucro JSON strutturato contenente sia il risultato che i metadati di esecuzione:

{
  "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": [{...}]
  }
}

Campi della risposta:

• success — Booleano che indica se il task è stato completato con successo
• result — Il valore di ritorno effettivo del tuo task (json, stringa, null in caso di fallimento, ecc.)
• error — Dettagli dell'errore se il task è fallito ({ error_type: string, message: string })
• execution — Metriche di performance:
  • task_name — Nome del task eseguito
  • duration_ms — Tempo di esecuzione in millisecondi
  • retries — Numero di tentativi di ripetizione effettuati
  • fuel_consumed — Risorse CPU utilizzate (vedi Livelli di Compute)
  • ram_used — Picco di memoria utilizzato in byte
  • host_requests — Elenco delle richieste host effettuate dal task

Accesso alla Rete