capsule

---

Capsule est un runtime permettant d'exécuter du code non fiable dans des environnements isolés. Chaque tâche s'exécute dans son propre bac à sable WebAssembly, offrant :

• Exécution isolée : chaque tâche s'exécute de manière isolée de votre système hôte
• Limites de ressources : définissez des limites de CPU, de mémoire et de délai d'expiration par tâche
• Nouvelles tentatives automatiques : gérez les échecs sans intervention manuelle
• Suivi du cycle de vie : surveillez quelles tâches sont en cours d'exécution, terminées ou en échec

Fonctionnement

Avec Python

Annotez simplement vos fonctions Python avec le décorateur @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"}

Avec TypeScript / JavaScript

Utilisez la fonction d'encapsulation task() avec un accès complet à l'écosystème 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] Le runtime nécessite une tâche nommée "main" comme point d'entrée. Python en créera une automatiquement si aucune n'est définie, mais il est recommandé de la définir explicitement.

Lorsque vous exécutez capsule run main.py (ou main.ts), votre code est compilé en un module WebAssembly et exécuté dans des bacs à sable isolés.

Chaque tâche fonctionne dans son propre bac à sable avec des limites de ressources configurables, garantissant que les échecs sont contenus et ne se propagent pas aux autres parties de votre workflow. Le système hôte contrôle chaque aspect de l'exécution, de l'allocation CPU via le comptage de carburant Wasm aux contraintes de mémoire et à l'application des délais d'expiration.

Premiers pas

Python

pip install capsule-run

Créez hello.py :

from capsule import task

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

Exécutez-le :

capsule run hello.py

TypeScript / JavaScript

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

Créez hello.ts :

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

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

Exécutez-le :

capsule run hello.ts

[!TIP] Ajoutez --verbose pour voir les détails d'exécution des tâches en temps réel.

Exécuter depuis votre code

La fonction run() vous permet d'exécuter des tâches par programmation depuis votre code au lieu d'utiliser la CLI. Les args sont automatiquement transmis comme paramètres à la tâche main.

Python

from capsule import run

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

Créez sandbox.py :

from capsule import task

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

TypeScript / JavaScript

[!IMPORTANT] Vous avez besoin de @capsule-run/cli dans vos dépendances pour utiliser les fonctions de runner en TypeScript.

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

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

Créez 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 vous recherchez une solution préconfigurée et prête à l'emploi, consultez l'adaptateur Python ou l'adaptateur TypeScript.

Documentation

Options de configuration des tâches

Configurez vos tâches avec ces paramètres :

Paramètre	Description	Type	Défaut	Exemple
name	Identifiant de la tâche	str	nom de la fonction (Python) / requis (TS)	"process_data"
compute	Niveau d'allocation CPU : "LOW", "MEDIUM" ou "HIGH"	str	"MEDIUM"	"HIGH"
ram	Limite de mémoire pour la tâche	str	illimité	"512MB", "2GB"
timeout	Temps d'exécution maximal	str	illimité	"30s", "5m", "1h"
max_retries / maxRetries	Nombre de tentatives de nouvelle exécution en cas d'échec	int	0	3
allowed_files / allowedFiles	Dossiers accessibles dans le bac à sable (avec mode d'accès optionnel)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	Domaines accessibles dans le bac à sable	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	Variables d'environnement accessibles dans le bac à sable	list	[]	["API_KEY"]

Niveaux de calcul

Capsule contrôle l'utilisation du CPU via le mécanisme de carburant de WebAssembly, qui mesure l'exécution des instructions. Le niveau de calcul détermine la quantité de carburant que votre tâche reçoit.

• LOW fournit une allocation minimale pour les tâches légères
• MEDIUM offre des ressources équilibrées pour les charges de travail typiques
• HIGH accorde un carburant maximal pour les opérations gourmandes en calcul
• CUSTOM pour spécifier une valeur de carburant exacte (par ex., compute="1000000") afin de contrôler précisément les limites d'exécution.

Format de réponse

Chaque tâche renvoie une enveloppe JSON structurée contenant à la fois le résultat et les métadonnées d'exécution :

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

Champs de réponse :

• success — Booléen indiquant si la tâche s'est terminée avec succès
• result — La valeur de retour réelle de votre tâche (json, string, null en cas d'échec, etc.)
• error — Détails de l'erreur si la tâche a échoué ({ error_type: string, message: string })
• execution — Métriques de performance :
  • task_name — Nom de la tâche exécutée
  • duration_ms — Temps d'exécution en millisecondes
  • retries — Nombre de tentatives de nouvelle exécution effectuées
  • fuel_consumed — Ressources CPU utilisées (voir Niveaux de calcul)
  • ram_used — Mémoire maximale utilisée en octets
  • host_requests — Liste des requêtes hôtes effectuées par la tâche

Accès réseau