capsule

---

Capsule ist eine Runtime zur Ausführung von nicht vertrauenswürdigem Code in isolierten Umgebungen. Jede Aufgabe läuft in ihrer eigenen WebAssembly-Sandbox und bietet:

• Isolierte Ausführung: Jede Aufgabe läuft isoliert von deinem Host-System
• Ressourcenlimits: Lege CPU-, Speicher- und Timeout-Limits pro Aufgabe fest
• Automatische Wiederholungen: Behandle Fehler ohne manuelles Eingreifen
• Lebenszyklus-Verfolgung: Überwache, welche Aufgaben laufen, abgeschlossen oder fehlgeschlagen sind

Funktionsweise

Mit Python

Versehe deine Python-Funktionen einfach mit dem @task-Dekorator:

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

Mit TypeScript / JavaScript

Verwende die task()-Wrapper-Funktion mit vollem Zugriff auf das npm-Ökosystem:

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] Die Runtime benötigt eine Aufgabe namens "main" als Einstiegspunkt. Python erstellt automatisch eine, wenn keine definiert ist, aber es wird empfohlen, sie explizit festzulegen.

Wenn du capsule run main.py (oder main.ts) ausführst, wird dein Code in ein WebAssembly-Modul kompiliert und in isolierten Sandboxes ausgeführt.

Jede Aufgabe arbeitet innerhalb ihrer eigenen Sandbox mit konfigurierbaren Ressourcenlimits, wodurch sichergestellt wird, dass Fehler eingedämmt werden und nicht auf andere Teile deines Workflows übergreifen. Das Host-System kontrolliert jeden Aspekt der Ausführung, von der CPU-Zuweisung über Wasm-Fuel-Metering bis hin zu Speicherbeschränkungen und Timeout-Durchsetzung.

Erste Schritte

Python

pip install capsule-run

Erstelle hello.py:

from capsule import task

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

Führe es aus:

capsule run hello.py

TypeScript / JavaScript

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

Erstelle hello.ts:

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

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

Führe es aus:

capsule run hello.ts

[!TIP] Füge --verbose hinzu, um Details zur Aufgabenausführung in Echtzeit zu sehen.

Aus deinem Code heraus ausführen

Die run()-Funktion ermöglicht es dir, Aufgaben programmatisch aus deinem Code heraus auszuführen, anstatt die CLI zu verwenden. Die args werden automatisch als Parameter an die main-Aufgabe weitergeleitet.

Python

from capsule import run

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

Erstelle sandbox.py:

from capsule import task

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

TypeScript / JavaScript

[!IMPORTANT] Du benötigst @capsule-run/cli in deinen Abhängigkeiten, um die Runner-Funktionen in TypeScript zu verwenden.

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

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

Erstelle 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] Wenn du nach einer vorkonfigurierten, einsatzbereiten Lösung suchst, schau dir den Python-Adapter oder den TypeScript-Adapter an.

Dokumentation

Konfigurationsoptionen für Aufgaben

Konfiguriere deine Aufgaben mit diesen Parametern:

Parameter	Beschreibung	Typ	Standard	Beispiel
name	Aufgabenbezeichner	str	Funktionsname (Python) / erforderlich (TS)	"process_data"
compute	CPU-Zuweisungsstufe: "LOW", "MEDIUM" oder "HIGH"	str	"MEDIUM"	"HIGH"
ram	Speicherlimit für die Aufgabe	str	unbegrenzt	"512MB", "2GB"
timeout	Maximale Ausführungszeit	str	unbegrenzt	"30s", "5m", "1h"
max_retries / maxRetries	Anzahl der Wiederholungsversuche bei Fehlern	int	0	3
allowed_files / allowedFiles	Ordner, auf die in der Sandbox zugegriffen werden kann (mit optionalem Zugriffsmodus)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	Domains, auf die in der Sandbox zugegriffen werden kann	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	Umgebungsvariablen, auf die in der Sandbox zugegriffen werden kann	list	[]	["API_KEY"]

Compute-Stufen

Capsule steuert die CPU-Nutzung über den Fuel-Mechanismus von WebAssembly, der die Instruktionsausführung messen. Die Compute-Stufe bestimmt, wie viel Fuel deine Aufgabe erhält.

• LOW bietet eine minimale Zuweisung für leichtgewichtige Aufgaben
• MEDIUM bietet ausgewogene Ressourcen für typische Workloads
• HIGH gewährt maximalen Fuel für rechenintensive Operationen
• CUSTOM, um einen exakten Fuel-Wert anzugeben (z. B. compute="1000000") für präzise Kontrolle über Ausführungslimits.

Antwortformat

Jede Aufgabe gibt einen strukturierten JSON-Umschlag zurück, der sowohl das Ergebnis als auch Ausführungsmetadaten enthält:

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

Antwortfelder:

• success — Boolescher Wert, der angibt, ob die Aufgabe erfolgreich abgeschlossen wurde
• result — Der tatsächliche Rückgabewert deiner Aufgabe (json, string, null bei Fehler usw.)
• error — Fehlerdetails, wenn die Aufgabe fehlgeschlagen ist ({ error_type: string, message: string })
• execution — Leistungsmetriken:
  • task_name — Name der ausgeführten Aufgabe
  • duration_ms — Ausführungszeit in Millisekunden
  • retries — Anzahl der aufgetretenen Wiederholungsversuche
  • fuel_consumed — Verwendete CPU-Ressourcen (siehe Compute-Stufen)
  • ram_used — Spitzenspeicherverbrauch in Bytes
  • host_requests — Liste der von der Aufgabe gestellten Host-Anfragen

Netzwerkzugriff