mavdol/capsule/mcp-server

Getting Started • Documentation • Issues • Contributing
---
is a runtime for executing untrusted code in isolated environments. Each task runs inside its own WebAssembly sandbox, providing:
- **Isolated execution**: Each task runs isolated from your host system
- **Resource limits**: Set CPU, memory, and timeout limits per task
- **Automatic retries**: Handle failures without manual intervention
- **Lifecycle tracking**: Monitor which tasks are running, completed, or failed
How It Works
With Python
Simply annotate your Python functions with the @task decorator:
With TypeScript / JavaScript
Use the task() wrapper function with full access to the npm ecosystem:
> [!NOTE]
> The runtime requires a task named "main" as the entry point. Python will create one automatically if none is defined, but it's recommended to set it explicitly.
When you run capsule run main.py (or main.ts), your code is compiled into a WebAssembly module and executed in isolated sandboxes.
Each task operates within its own sandbox with configurable resource limits, ensuring that failures are contained and don't cascade to other parts of your workflow. The host system controls every aspect of execution, from CPU allocation via Wasm fuel metering to memory constraints and timeout enforcement.
Getting Started
Python
Create hello.py:
Run it:
TypeScript / JavaScript
Create hello.ts:
Run it:
> [!TIP]
> Add --verbose to see real-time task execution details.
Run From Your Code
The run() function lets you execute tasks programmatically from your code instead of using the CLI. The args are automatically forwarded as parameters to the main task.
Python
Create sandbox.py:
TypeScript / JavaScript
> [!IMPORTANT]
> You need @capsule-run/cli in your dependencies to use the runner functions in TypeScript.
Create sandbox.ts:
> [!TIP]
> If you're looking for a pre-configured, ready-to-use solution, check out the Python adapter or TypeScript adapter.
Documentation
Task Configuration Options
Configure your tasks with these parameters:
| Parameter | Description | Type | Default | Example |
|-----------|-------------|------|---------|---------|
| name | Task identifier | str | function name (Python) / *required* (TS) | "process_data" |
| compute | CPU allocation level: "LOW", "MEDIUM", or "HIGH" | str | "MEDIUM" | "HIGH" |
| ram | Memory limit for the task | str | unlimited | "512MB", "2GB" |
| timeout | Maximum execution time | str | unlimited | "30s", "5m", "1h" |
| max_retries / maxRetries | Number of retry attempts on failure | int | 0 | 3 |
| allowed_files / allowedFiles | Folders accessible in the sandbox (with optional access mode) | list | [] | ["./data"], [{"path": "./data", "mode": "ro"}] |
| allowed_hosts / allowedHosts | Domains accessible in the sandbox | list | [] | ["api.openai.com", "*.anthropic.com"] |
| env_variables / envVariables | Environment variables accessible in the sandbox | list | [] | ["API_KEY"] |
Compute Levels
Capsule controls CPU usage through WebAssembly's **fuel mechanism**, which meters instruction execution. The compute level determines how much fuel your task receives.
- **LOW** provides minimal allocation for lightweight tasks
- **MEDIUM** offers balanced resources for typical workloads
- **HIGH** grants maximum fuel for compute-intensive operations
- **CUSTOM** to specify an exact fuel value (e.g., compute="1000000") for precise control over execution limits.
Response Format
Every task returns a structured JSON envelope containing both the result and execution metadata:
**Response fields:**
- success — Boolean indicating whether the task completed successfully
- result — The actual return value from your task (json, string, null on failure etc.)