---

Übersicht

Capsule ist eine Laufzeitumgebung zur Ausführung von nicht vertrauenswürdigem Code in isolierten Umgebungen. Jeder Task läuft in seiner eigenen WebAssembly-Sandbox und bietet:

• Isolierte Ausführung: Jeder Task läuft isoliert von Ihrem Host-System
• Ressourcenbegrenzung: Setzen Sie CPU-, Speicher- und Zeitlimits pro Task
• Automatische Wiederholungen: Fehlerbehandlung ohne manuelles Eingreifen
• Lebenszyklusverfolgung: Überwachen Sie, welche Tasks laufen, abgeschlossen oder fehlgeschlagen sind

So funktioniert's

Mit Python

Dekorieren Sie Ihre 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:
    """Verarbeitet Daten in einer isolierten, ressourcengesteuerten Umgebung."""
    # Ihr Code läuft sicher in einer Wasm-Sandbox
    return {"processed": len(dataset), "status": "complete"}

Mit TypeScript / JavaScript

Verwenden Sie 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 => {
  // Ihr Code läuft sicher in einer Wasm-Sandbox
  return { processed: dataset.length, status: "complete" };
});

[!HINWEIS] Die Laufzeitumgebung benötigt einen Task namens "main" als Einstiegspunkt. Python erstellt automatisch einen, falls keiner definiert ist, es wird jedoch empfohlen, ihn explizit zu setzen.

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

Jeder Task arbeitet innerhalb seiner eigenen Sandbox mit konfigurierbaren Ressourcenlimits, sodass Fehler eingedämmt werden und nicht auf andere Teile Ihres Workflows übergreifen. Das Host-System steuert jeden Aspekt der Ausführung, von der CPU-Zuteilung über Wasm-Fuel-Metering bis hin zu Speicherbeschränkungen und Timeout-Erzwingung.

Erste Schritte

Python

pip install capsule-run

Erstellen Sie hello.py:

from capsule import task

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

Führen Sie es aus:

capsule run hello.py

TypeScript / JavaScript

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

Erstellen Sie hello.ts:

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

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

Führen Sie es aus:

capsule run hello.ts

[!TIPP] Fügen Sie --verbose hinzu, um Echtzeitdetails der Task-Ausführung zu sehen.

Aus Ihrem Code ausführen

Die run()-Funktion ermöglicht es Ihnen, Tasks programmatisch aus Ihrem Code auszuführen, anstatt die CLI zu verwenden. Die args werden automatisch als Parameter an den main-Task weitergeleitet.

Python

from capsule import run

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

Erstellen Sie sandbox.py:

from capsule import task

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

TypeScript / JavaScript

[!WICHTIG] Sie benötigen @capsule-run/cli in Ihren 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']
});

Erstellen Sie sandbox.ts:

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

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (code: string): string => {
  return eval(code);
});

[!TIPP] Wenn Sie nach einer vorkonfigurierten, einsatzbereiten Lösung suchen, schauen Sie sich den Python-Adapter oder den TypeScript-Adapter an.

Dokumentation

Task-Konfigurationsoptionen

Konfigurieren Sie Ihre Tasks mit diesen Parametern:

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

Berechnungsstufen

Capsule steuert die CPU-Nutzung über den Fuel-Mechanismus von WebAssembly, der die Befehlsausführung misst. Die Berechnungsstufe bestimmt, wie viel Fuel Ihr Task erhält.

• LOW bietet minimale Zuteilung für leichte Tasks
• MEDIUM bietet ausgewogene Ressourcen für typische Arbeitslasten
• HIGH gewährt maximales Fuel für rechenintensive Operationen
• CUSTOM zum Angeben eines exakten Fuel-Werts (z. B. compute="1000000") für präzise Kontrolle über Ausführungslimits.

Antwortformat

Jeder Task gibt einen strukturierten JSON-Envelope 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 der Task erfolgreich abgeschlossen wurde
• result — Der tatsächliche Rückgabewert Ihres Tasks (json, string, null bei Fehler usw.)
• error — Fehlerdetails, falls der Task fehlgeschlagen ist ({ error_type: string, message: string })
• execution — Leistungsmetriken:
  • task_name — Name des ausgeführten Tasks
  • duration_ms — Ausführungszeit in Millisekunden
  • retries — Anzahl der aufgetretenen Wiederholungsversuche
  • fuel_consumed — Verbrauchte CPU-Ressourcen (siehe Berechnungsstufen)
  • ram_used — Spitzen-Speichernutzung in Bytes
  • host_requests — Liste der vom Task durchgeführten Host-Anfragen

Netzwerkzugriff