---

Visão Geral

O Capsule é um runtime para executar código não confiável em ambientes isolados. Cada tarefa é executada dentro de seu próprio sandbox WebAssembly, fornecendo:

• Execução isolada: Cada tarefa é executada isolada do seu sistema host
• Limites de recursos: Defina limites de CPU, memória e tempo limite por tarefa
• Repetições automáticas: Lide com falhas sem intervenção manual
• Rastreamento do ciclo de vida: Monitore quais tarefas estão em execução, concluídas ou falharam

Como Funciona

Com Python

Basta anotar suas funções Python com o decorador @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."""
    # Seu código é executado com segurança em um sandbox Wasm
    return {"processed": len(dataset), "status": "complete"}

Com TypeScript / JavaScript

Use a função wrapper task() com acesso total ao ecossistema 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 => {
  // Seu código é executado com segurança em um sandbox Wasm
  return { processed: dataset.length, status: "complete" };
});

[!NOTE] O runtime requer uma tarefa chamada "main" como ponto de entrada. O Python criará uma automaticamente se nenhuma for definida, mas é recomendado defini-la explicitamente.

Quando você executa capsule run main.py (ou main.ts), seu código é compilado em um módulo WebAssembly e executado em sandboxes isolados.

Cada tarefa opera dentro de seu próprio sandbox com limites de recursos configuráveis, garantindo que as falhas sejam contidas e não se propaguem para outras partes do seu fluxo de trabalho. O sistema host controla todos os aspectos da execução, desde a alocação de CPU via medição de combustível Wasm até restrições de memória e cumprimento de tempo limite.

Introdução

Python

pip install capsule-run

Crie hello.py:

from capsule import task

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

Execute:

capsule run hello.py

TypeScript / JavaScript

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

Crie hello.ts:

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

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

Execute:

capsule run hello.ts

[!TIP] Adicione --verbose para ver detalhes da execução da tarefa em tempo real.

Executar a Partir do Seu Código

A função run() permite executar tarefas programaticamente a partir do seu código em vez de usar a CLI. Os args são automaticamente encaminhados como parâmetros para a tarefa main.

Python

from capsule import run

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

Crie sandbox.py:

from capsule import task

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

TypeScript / JavaScript

[!IMPORTANT] Você precisa do @capsule-run/cli nas suas dependências para usar as funções runner em TypeScript.

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

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

Crie 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] Se você está procurando uma solução pré-configurada e pronta para uso, confira o adaptador Python ou o adaptador TypeScript.

Documentação

Opções de Configuração de Tarefas

Configure suas tarefas com estes parâmetros:

Parâmetro	Descrição	Tipo	Padrão	Exemplo
name	Identificador da tarefa	str	nome da função (Python) / obrigatório (TS)	"process_data"
compute	Nível de alocação de CPU: "LOW", "MEDIUM" ou "HIGH"	str	"MEDIUM"	"HIGH"
ram	Limite de memória para a tarefa	str	ilimitado	"512MB", "2GB"
timeout	Tempo máximo de execução	str	ilimitado	"30s", "5m", "1h"
max_retries / maxRetries	Número de tentativas de repetição em caso de falha	int	0	3
allowed_files / allowedFiles	Pastas acessíveis no sandbox (com modo de acesso opcional)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	Domínios acessíveis no sandbox	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	Variáveis de ambiente acessíveis no sandbox	list	[]	["API_KEY"]

Níveis de Computação

O Capsule controla o uso da CPU através do mecanismo de combustível do WebAssembly, que mede a execução de instruções. O nível de computação determina quanto combustível sua tarefa recebe.

• LOW fornece alocação mínima para tarefas leves
• MEDIUM oferece recursos balanceados para cargas de trabalho típicas
• HIGH concede combustível máximo para operações intensivas de computação
• CUSTOM para especificar um valor exato de combustível (ex.: compute="1000000") para controle preciso sobre os limites de execução.

Formato de Resposta

Cada tarefa retorna um envelope JSON estruturado contendo tanto o resultado quanto os metadados de execução:

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

Campos da resposta:

• success — Booleano indicando se a tarefa foi concluída com sucesso
• result — O valor de retorno real da sua tarefa (json, string, null em caso de falha, etc.)
• error — Detalhes do erro se a tarefa falhou ({ error_type: string, message: string })
• execution — Métricas de desempenho:
  • task_name — Nome da tarefa executada
  • duration_ms — Tempo de execução em milissegundos
  • retries — Número de tentativas de repetição que ocorreram
  • fuel_consumed — Recursos de CPU usados (veja Níveis de Computação)
  • ram_used — Pico de memória usado em bytes
  • host_requests — Lista de requisições ao host feitas pela tarefa

Acesso à Rede

As tarefas podem fazer requisições HTTP para domínios especificados em allowed_hosts. Por padrão, nenhuma requisição de saída é permitida ([]). Forneça uma lista de permissão de domínios para conceder acesso, ou use ["*"] para permitir todos os domínios.

Python