evolve
"Evolve SDK development for TypeScript and Python. Use when building applications with Evolve to run AI agents (Claude, Codex, Gemini, Qwen, Kimi, OpenCode) in secure sandboxes. Triggers: (1) Creating Evolve applications, (2) Configuring agents with skills, Composio, MCP servers, (3) Using Swarm abstractions (map, filter, reduce, bestOf/best_of, verify), (4) Building Pipelines, (5) Structured output with schemas, (6) Session management, streaming, observability, (7) Checkpointing, storage & StorageClient, (8) Cost tracking (per-run and per-session spend), (9) Historical sessions & trace download via sessions() client."
Resources
1Install
npx skillscat add evolving-machines-lab/evolve/skills-evolve Install via the SkillsCat registry.
Evolve SDK
Build applications that run CLI agents in secure cloud sandboxes.
Repo: https://github.com/evolving-machines-lab/evolve
Language Detection
Determine the language from (in priority order):
- User specification — if the user states a language, use it
- Project signals — imports, file extensions, package.json vs pyproject.toml
- Ask — if ambiguous, ask the user
- TypeScript (
@evolvingmachines/sdk) — read from references/typescript/ - Python (
evolve-sdk) — read from references/python/
Required Reading
Always read these three references for the detected language before writing any Evolve code:
TypeScript:
- 01-getting-started.md — Installation, authentication (Gateway/BYOK), core lifecycle, streaming basics, agent reference table
- 02-configuration.md — Sandbox providers, full builder API, agent skills catalog, Composio (1000+ integrations), MCP servers
- 03-runtime.md — run(), executeCommand(), upload/download files, session controls, workspace layout, structured output, session management, storage & checkpointing, StorageClient, sessions() client, cost tracking, observability, error handling
Python:
- 01-getting-started.md — Installation, authentication (Gateway/BYOK), core lifecycle, streaming basics, agent reference table
- 02-configuration.md — Sandbox providers, full constructor API, agent skills catalog, Composio (1000+ integrations), MCP servers
- 03-runtime.md — run(), execute_command(), upload/download files, session controls, workspace layout, structured output, session management, storage & checkpointing, StorageClient, sessions() client, cost tracking, observability, error handling
Critical Constraints
- Model names — Only use exact names from the Agent Reference table. Do not invent or guess model identifiers.
- Cleanup — Always call
kill()when done. Sandboxes bill until destroyed.
Additional References
Read on demand when the user's task requires them:
| When to read | TypeScript | Python |
|---|---|---|
| Building a UI, handling real-time events, parsing tool calls, browser-use | 04-streaming.md | 04-streaming.md |
| Parallel agents (map/filter/reduce/bestOf/verify), Pipeline chaining | 05-swarm-pipeline.md | 05-swarm-pipeline.md |
Topic Index
Getting Started
| Topic | TypeScript | Python |
|---|---|---|
| Installation & requirements | TS | PY |
| Quick start (3 steps) | TS | PY |
| Core lifecycle (run, output, kill) | TS | PY |
| Streaming basics | TS | PY |
| Gateway vs BYOK mode | TS | PY |
| BYO subscriptions (Claude Max, Codex, Gemini) | TS | PY |
| Supported agents, models & defaults | TS | PY |
Configuration
| Topic | TypeScript | Python |
|---|---|---|
| Sandbox providers (E2B, Modal, Daytona) | TS | PY |
| Provider auto-resolution from env | TS | PY |
| Full builder/constructor API | TS | PY |
| Agent skills catalog | TS | PY |
| Composio (auth paths, tool filtering, types) | TS | PY |
| MCP server config (STDIO / HTTP / SSE) | TS | PY |
Runtime
| Topic | TypeScript | Python |
|---|---|---|
| run() options (timeout, background, checkpoint) | TS | PY |
| executeCommand() / execute_command() | TS | PY |
| Upload files to sandbox | TS | PY |
| Download output files | TS | PY |
| Session controls (interrupt, pause, resume, kill) | TS | PY |
| Port forwarding | TS | PY |
| Workspace filesystem layout | TS | PY |
| Structured output (Zod / Pydantic / JSON Schema) | TS | PY |
| Multi-turn conversations | TS | PY |
| Pause, resume, reconnect, switch sandboxes | TS | PY |
| Storage & checkpointing (gateway mode) | TS | PY |
| StorageClient (list, get, download checkpoints) | TS | PY |
| Checkpoint lineage & restore | TS | PY |
| Historical sessions & trace download | TS | PY |
| Cost tracking (per-run & per-session spend) | TS | PY |
| Observability (dashboard + local logs) | TS | PY |
| Error handling | TS | PY |
Streaming
| Topic | TypeScript | Python |
|---|---|---|
| Event listeners (content, lifecycle, stdout, stderr) | TS | PY |
| LifecycleEvent & LifecycleReason | TS | PY |
| OutputEvent & SessionUpdate types | TS | PY |
| Tool events (ToolCall, ToolCallUpdate, ToolKind) | TS | PY |
| Browser-use detection & URL extraction | TS | PY |
| UI integration example | TS | PY |
Swarm & Pipeline
| Topic | TypeScript | Python |
|---|---|---|
| Swarm setup (config, concurrency, retry) | TS | PY |
| Input types (FileMap, folders) | TS | PY |
| bestOf / best_of (N candidates + judge) | TS | PY |
| map (parallel processing) | TS | PY |
| filter (evaluate + threshold) | TS | PY |
| reduce (synthesize many to one) | TS | PY |
| verify (quality gate with feedback loop) | TS | PY |
| Result types (SwarmResult, ReduceResult, BestOfResult) | TS | PY |
| Chaining operations | TS | PY |
| Pipeline (fluent chaining, events, terminal) | TS | PY |
Self-Update
Pull the latest skill from the official repo:
git clone --depth 1 --filter=blob:none --sparse https://github.com/evolving-machines-lab/evolve.git /tmp/evolve-update \
&& cd /tmp/evolve-update \
&& git sparse-checkout set skills/evolve \
&& cp -r skills/evolve/* <SKILL_INSTALL_DIR>/evolve/ \
&& rm -rf /tmp/evolve-updateReplace <SKILL_INSTALL_DIR> with the skill installation path (e.g. ~/.claude/skills/, ~/.codex/skills/, ~/.gemini/skills/).
Install
npx skillscat add evolving-machines-lab/evolve/skills-evolve Install via the SkillsCat registry.