capsule

---

Capsule — это среда выполнения для запуска недоверенного кода в изолированных окружениях. Каждая задача выполняется внутри собственной песочницы WebAssembly, обеспечивая:

• Изолированное выполнение: каждая задача выполняется изолированно от вашей хост-системы
• Ограничения ресурсов: задавайте лимиты CPU, памяти и таймаута для каждой задачи
• Автоматические повторные попытки: обработка сбоев без ручного вмешательства
• Отслеживание жизненного цикла: мониторинг того, какие задачи выполняются, завершены или завершились с ошибкой

Как это работает

С помощью Python

Просто аннотируйте свои функции Python декоратором @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"}

С помощью TypeScript / JavaScript

Используйте функцию-обёртку task() с полным доступом к экосистеме 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] Среда выполнения требует задачу с именем "main" в качестве точки входа. Python создаст её автоматически, если она не определена, но рекомендуется задавать её явно.

Когда вы запускаете capsule run main.py (или main.ts), ваш код компилируется в модуль WebAssembly и выполняется в изолированных песочницах.

Каждая задача работает в собственной песочнице с настраиваемыми ограничениями ресурсов, гарантируя, что сбои локализуются и не распространяются на другие части вашего рабочего процесса. Хост-система контролирует каждый аспект выполнения — от выделения CPU через механизм учёта топлива Wasm до ограничений памяти и принудительного применения таймаутов.

Начало работы

Python

pip install capsule-run

Создайте hello.py:

from capsule import task

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

Запустите его:

capsule run hello.py

TypeScript / JavaScript

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

Создайте hello.ts:

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

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

Запустите его:

capsule run hello.ts

[!TIP] Добавьте --verbose, чтобы видеть детали выполнения задач в реальном времени.

Запуск из вашего кода

Функция run() позволяет выполнять задачи программно из вашего кода вместо использования CLI. Аргументы args автоматически передаются как параметры задаче main.

Python

from capsule import run

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

Создайте sandbox.py:

from capsule import task

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

TypeScript / JavaScript

[!IMPORTANT] Вам нужен @capsule-run/cli в ваших зависимостях, чтобы использовать функции запуска в TypeScript.

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

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

Создайте 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] Если вы ищете предварительно настроенное, готовое к использованию решение, ознакомьтесь с адаптером для Python или адаптером для TypeScript.

Документация

Параметры конфигурации задач

Настраивайте свои задачи с помощью этих параметров:

Параметр	Описание	Тип	По умолчанию	Пример
name	Идентификатор задачи	str	имя функции (Python) / обязательно (TS)	"process_data"
compute	Уровень выделения CPU: "LOW", "MEDIUM" или "HIGH"	str	"MEDIUM"	"HIGH"
ram	Лимит памяти для задачи	str	неограничен	"512MB", "2GB"
timeout	Максимальное время выполнения	str	неограничен	"30s", "5m", "1h"
max_retries / maxRetries	Количество повторных попыток при сбое	int	0	3
allowed_files / allowedFiles	Папки, доступные в песочнице (с необязательным режимом доступа)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	Домены, доступные в песочнице	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	Переменные окружения, доступные в песочнице	list	[]	["API_KEY"]

Уровни вычислений

Capsule управляет использованием CPU через механизм топлива WebAssembly, который измеряет выполнение инструкций. Уровень вычислений определяет, сколько топлива получает ваша задача.

• LOW обеспечивает минимальное выделение для лёгких задач
• MEDIUM предлагает сбалансированные ресурсы для типичных рабочих нагрузок
• HIGH предоставляет максимальное топливо для ресурсоёмких операций
• CUSTOM позволяет указать точное значение топлива (например, compute="1000000") для точного контроля над лимитами выполнения.

Формат ответа

Каждая задача возвращает структурированный JSON-конверт, содержащий как результат, так и метаданные выполнения:

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

Поля ответа:

• success — логическое значение, указывающее, успешно ли завершилась задача
• result — фактическое возвращаемое значение вашей задачи (json, string, null при сбое и т. д.)
• error — детали ошибки, если задача завершилась с ошибкой ({ error_type: string, message: string })
• execution — метрики производительности:
  • task_name — имя выполненной задачи
  • duration_ms — время выполнения в миллисекундах
  • retries — количество выполненных повторных попыток
  • fuel_consumed — использованные ресурсы CPU (см. Уровни вычислений)
  • ram_used — пиковое использование памяти в байтах
  • host_requests — список запросов к хосту, сделанных задачей

Сетевой доступ

Задачи могут выполнять HTTP-запросы к доменам, указанным в allowed_hosts. По умолчанию исходящие запросы запрещены ([]). Укажите список разрешённых доменов для предоставления доступа или используйте ["*"], чтобы разрешить все домены.

Python