evolve

name

evolve

description

Evolve SDK development for TypeScript and Python. Use when building applications with Evolve to run AI agents (Claude, Codex, Gemini, Qwen, Kimi, OpenCode, Droid) in secure sandboxes. Triggers: (1) Creating Evolve applications, (2) Configuring agents with skills, Integrations, 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.

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):

1. User specification — if the user states a language, use it
2. Project signals — imports, file extensions, package.json vs pyproject.toml
3. 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, managed BYO provider keys, direct provider-key mode), core lifecycle, streaming basics, agent reference table
• 02-configuration.md — Sandbox providers, full builder API, agent skills catalog, Managed 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, managed BYO provider keys, direct provider-key mode), core lifecycle, streaming basics, agent reference table
• 02-configuration.md — Sandbox providers, full constructor API, agent skills catalog, Managed 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.
  • TS | PY
• Cleanup — Always call kill() when done. Sandboxes bill until destroyed.
  • TS | PY

Additional References

Read on demand when the user's task requires them:

When to read	TypeScript	Python
Building a UI, handling real-time events	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, managed BYO provider keys, and direct provider-key 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
Browser automation guide (setup, live view, replay)	TS	PY
Browser credentials (saved website logins)	TS	PY
Agent plugins/extensions	TS	PY
Agent skills catalog	TS	PY
Managed secrets (Dashboard-stored env secrets)	TS	PY
Managed integrations (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 lifecycle event fields	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-update

Replace <SKILL_INSTALL_DIR> with the skill installation path (e.g. ~/.claude/skills/, ~/.codex/skills/, ~/.gemini/skills/).