---

Обзор

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

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

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

В 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:
    """Обработка данных в изолированном окружении с контролем ресурсов."""
    # Ваш код безопасно выполняется в песочнице Wasm
    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 => {
  // Ваш код безопасно выполняется в песочнице Wasm
  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] Для использования функций запуска в TypeScript требуется @capsule-run/cli в зависимостях.

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, который дозирует выполнение инструкций. Уровень compute определяет, сколько топлива получает задача.

• 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, строка, null при ошибке и т.д.)
• error — детали ошибки, если задача завершилась сбоем ({ error_type: string, message: string })
• execution — метрики производительности:
  • task_name — имя выполненной задачи
  • duration_ms — время выполнения в миллисекундах
  • retries — количество произошедших повторов
  • fuel_consumed — использованные ресурсы CPU (см. Уровни вычислительных ресурсов)
  • ram_used — пиковое использование памяти в байтах
  • host_requests — список запросов к хосту, сделанных задачей

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

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

Python

import json
from capsule import task
from urllib.request import urlopen