capsule

---

Capsule è un runtime per l'esecuzione di codice non attendibile in ambienti isolati. Ogni attività viene eseguita all'interno del proprio sandbox WebAssembly, offrendo:

• Esecuzione isolata: Ogni attività viene eseguita isolata dal sistema host
• Limiti di risorse: Imposta limiti di CPU, memoria e timeout per attività
• Tentativi automatici: Gestisci i fallimenti senza intervento manuale
• Monitoraggio del ciclo di vita: Monitora quali attività sono in esecuzione, completate o fallite

Come Funziona

Con Python

Basta annotare le tue 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:
    """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 funzione wrapper task() con pieno accesso 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 => {
  // Your code runs safely in a Wasm sandbox
  return { processed: dataset.length, status: "complete" };
});

[!NOTE] Il runtime richiede un'attività denominata "main" come punto di ingresso. Python ne creerà una automaticamente se non ne viene definita nessuna, ma è consigliabile impostarla esplicitamente.

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

Ogni attività 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 il fuel metering di 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!"

Esegui:

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

Esegui:

capsule run hello.ts

[!TIP] Aggiungi --verbose per vedere i dettagli dell'esecuzione delle attività in tempo reale.

Esegui Dal Tuo Codice

La funzione run() ti permette di eseguire attività programmaticamente dal tuo codice invece di usare la CLI. Gli args vengono automaticamente inoltrati come parametri all'attività 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] Hai bisogno di @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: ['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] Se stai cercando una soluzione preconfigurata e pronta all'uso, dai un'occhiata all'adattatore Python o all'adattatore TypeScript.

Documentazione

Opzioni di Configurazione delle Attività

Configura le tue attività con questi parametri:

Parametro	Descrizione	Tipo	Predefinito	Esempio
name	Identificatore dell'attività	str	nome della funzione (Python) / obbligatorio (TS)	"process_data"
compute	Livello di allocazione CPU: "LOW", "MEDIUM", o "HIGH"	str	"MEDIUM"	"HIGH"
ram	Limite di memoria per l'attività	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 nel sandbox (con modalità di accesso opzionale)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	Domini accessibili nel sandbox	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	Variabili d'ambiente accessibili nel sandbox	list	[]	["API_KEY"]

Livelli di Calcolo

Capsule controlla l'utilizzo della CPU attraverso il meccanismo del fuel di WebAssembly, che misura l'esecuzione delle istruzioni. Il livello di calcolo determina quanto fuel riceve la tua attività.

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

Formato della Risposta

Ogni attività restituisce un envelope 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 l'attività è stata completata con successo
• result — Il valore di ritorno effettivo della tua attività (json, string, null in caso di fallimento ecc.)
• error — Dettagli dell'errore se l'attività è fallita ({ error_type: string, message: string })
• execution — Metriche di prestazione:
  • task_name — Nome dell'attività eseguita
  • duration_ms — Tempo di esecuzione in millisecondi
  • retries — Numero di tentativi di ripetizione effettuati
  • fuel_consumed — Risorse CPU utilizzate (vedi Livelli di Calcolo)
  • ram_used — Memoria di picco utilizzata in byte
  • host_requests — Elenco delle richieste host effettuate dall'attività

Accesso alla Rete