SkillLite

---

---

Pick your path

Default (recommended): pip install skilllite → OS-level sandbox + MCP in Cursor, Claude Desktop, OpenCode, or your own agent. You do not need the desktop app or the full SkillLite agent loop to get the core value.

One repository ships several entry points. Each row links to the English hub; 中文 is on that page if you prefer it.

---

A lightweight secure Self-evolution engine built in Rust, featuring a built-in native system-level sandbox, zero dependencies, and fully local execution.

We built the most secure skill sandbox in the ecosystem (20/20 security score). Then we realized: the real value isn’t just safe execution — it’s safe evolution.

[]

Architecture

┌──────────────────────────────────────────────────────────────┐
│  Self-Evolving Engine（自进化引擎）                             │
│                                                              │
│  Immutable Core (compiled into binary, never self-modifies)  │
│  ├─ Agent loop, LLM orchestration, tool execution            │
│  ├─ Config, metadata, path validation                        │
│  └─ Evolution engine: feedback → reflect → evolve → verify   │
│                                                              │
│  Evolvable Data (local files, auto-improves over use)        │
│  ├─ Prompts   — system / planning / execution prompts        │
│  ├─ Memory    — task patterns, tool effects, failure lessons  │
│  └─ Skills    — auto-generated skills from repeated patterns  │
│                         ▼                                    │
│          all evolved artifacts must pass ▼                    │
├──────────────────────────────────────────────────────────────┤
│  Security Sandbox（安全沙箱）                                  │
│                                                              │
│  Full-chain defense across the entire skill lifecycle:       │
│  ├─ Install-time: static scan + LLM analysis + supply-chain  │
│  ├─ Pre-execution: two-phase confirm + integrity check       │
│  └─ Runtime: OS-native isolation (Seatbelt / bwrap / seccomp)│
│     ├─ Process-exec whitelist, FS / network / IPC lockdown   │
│     └─ Resource limits (CPU / mem / fork / fsize)            │
└──────────────────────────────────────────────────────────────┘

Why two layers, not one? Evolution without safety is reckless — evolved skills could exfiltrate data or consume unbounded resources. Safety without evolution is static — the Agent never improves. SkillLite welds them together: the evolution engine produces new prompts, memory, and skills; the sandbox layer ensures every evolved artifact passes L3 security scanning + OS-level isolation before execution. Evolution is auditable, rollbackable, and never modifies the core binary.

Measured on macOS ARM64, release build. Sandbox RSS is dominated by the embedded Python process.

Use the full stack or just the sandbox: skilllite gives you evolution + agent + sandbox. skilllite-sandbox is a standalone binary (or MCP server) that any agent framework can adopt — no need to buy into the full SkillLite stack.

---

🧬 Intelligence: evolution without lowering the safety bar

Many products now advertise self-adapting or self-evolving agents. SkillLite’s stance is narrower and easier to keep accurate over time: prompts, memory, and skills may evolve, but they stay behind the same immutable core and full-chain sandbox as everything else — install-time scan, pre-execution gates, OS-level isolation, and governance (thresholds, backlog, rollback). Evolved artifacts are not exempt: they pass the same L3 checks + sandbox as manually installed skills.

---

🔒 Security: Full-Chain Defense

Most sandbox solutions only provide runtime isolation. SkillLite defends across the entire skill lifecycle — three layers in a single binary:

┌─────────────────────────────────────────────────┐
│ Layer 1 — Install-time Scanning                 │
│ ├─ Static rule scan (regex pattern matching)    │
│ ├─ LLM-assisted analysis (suspicious → confirm) │
│ └─ Supply-chain audit (PyPI / OSV vuln DB)      │
├─────────────────────────────────────────────────┤
│ Layer 2 — Pre-execution Authorization           │
│ ├─ Two-phase confirm (scan → user OK → run)     │
│ └─ Integrity check (hash tamper detection)      │
├─────────────────────────────────────────────────┤
│ Layer 3 — Runtime Sandbox                       │
│ ├─ OS-native isolation (Seatbelt / bwrap)       │
│ ├─ Process-exec whitelist (interpreter only)    │
│ ├─ Filesystem / network / IPC lockdown          │
│ └─ Resource limits (rlimit CPU/mem/fork/fsize)  │
└─────────────────────────────────────────────────┘

Runtime Security Scores (20-item test suite)

---

⚡ Performance

3-5x faster execution, 10x lower memory footprint vs Docker/SRT.

Benchmarking standard: SkillLite avoids the MicroVM layer entirely for local code execution: no guest kernel, VM monitor, image, or sandbox service stack. Its focused no-Python sandbox launch benchmark runs at 111 ms avg / 113 ms P95 with ~1.14 MB child peak RSS. This is process RSS, not directly comparable to MicroVM VMM-overhead/PSS figures. Real Python skill execution is reported separately: ~40 ms warm, ~492 ms cold, and ~10 MB RSS.

---

🎯 Why SkillLite?

In one sentence: Other agent frameworks are smart but unsafe, or safe but static. SkillLite is both — an Agent that gets measurably better over time, with every evolved artifact security-constrained by an OS-native sandbox.

• vs Agent frameworks (AutoGen, CrewAI, LangGraph): They provide orchestration but no built-in evolution or sandbox. SkillLite evolves autonomously and executes safely.
• vs Sandbox tools (E2B, Docker, Claude SRT): They provide isolation but no intelligence layer. SkillLite adds a full agent loop + self-evolution on top.
• vs Evolution platforms (OpenClaw Foundry, EvoAgentX): They enable evolution but without security constraints on evolved artifacts. SkillLite enforces L3 scanning + OS sandbox on everything it evolves.

Claude/Anthropic’s Claude Code Sandbox uses the same underlying sandbox tech (Seatbelt + bubblewrap). See Architecture Comparison for a detailed side-by-side analysis.

---

🚀 Quick Start

Installation (Recommended: pip)

pip install skilllite
skilllite init        # sandbox binary + skills/ + download skills
skilllite list        # verify installation

MCP in your IDE (recommended integration)

Use SkillLite as a sandbox + MCP server inside an agent you already run (Cursor, Claude Desktop, OpenCode, etc.):

pip install "skilllite[mcp]"   # if your platform needs MCP extras
skilllite init
skilllite mcp                  # stdio MCP server for the IDE

Wire the host: skilllite init-cursor · skilllite init-opencode. Step-by-step: Path 2 — Sandbox & MCP · MCP tutorial.

Zero-config quick start (auto-detect LLM, setup skills, launch chat):

skilllite quickstart

Run Your First Example

from skilllite import chat

result = chat("Calculate 15 * 27", skills_dir="skills")
print(result)

Or use the CLI: skilllite chat

Environment Configuration

cp .env.example .env   # Edit: BASE_URL, API_KEY, MODEL

Platform Support: macOS, Linux, and Windows (via WSL2 Bridge).

---

📚 Tutorials

👉 View All Tutorials

---

Evolution Arena (Evotown)

Repository: github.com/EXboys/evotown — evolution testing platform for evolution effect validation; any engine that can run under your harness and report into Evotown (HTTP ingest) works — SkillLite is a common option, not a requirement. A local clone for combined development may live at ./evotown/ (often gitignored in minimal checkouts).

Engine integration (draft): independent runners push results into Evotown over HTTP. Canonical docs on Evotown: ingest API v0.1 · OpenAPI. Mirror in this repo (SkillLite contributors): English · 中文 · OpenAPI.

---

💡 Usage

Direct Skill Execution

from skilllite import run_skill

result = run_skill("./skills/calculator", '{"operation": "add", "a": 15, "b": 27}')
print(result["text"])

Skill Repository Management

skilllite add owner/repo                    # Add all skills from a GitHub repo
skilllite add owner/repo@skill-name         # Add a specific skill by name
skilllite add ./local-path                  # Add from local directory
skilllite add ./downloaded-skill.zip        # Add from a downloaded local ZIP package
skilllite import-openclaw-skills            # Import from OpenClaw-style dirs (workspace/skills, ~/.openclaw/skills, …)
skilllite claw migrate --dry-run            # OpenClaw → SkillLite: skills, SOUL/MEMORY Markdown, optional secrets
skilllite list                              # List all installed skills
skilllite remove                # Remove an installed skill

Framework Integration

pip install langchain-skilllite   # LangChain adapter

from langchain_skilllite import SkillLiteToolkit
from langgraph.prebuilt import create_react_agent

tools = SkillLiteToolkit.from_directory(
    "./skills",
    sandbox_level=3,  # 1=no sandbox, 2=sandbox only, 3=sandbox+scan
    confirmation_callback=lambda report, sid: input("Continue? [y/N]: ").lower() == 'y'
)
agent = create_react_agent(ChatOpenAI(model="gpt-4"), tools)

See 05. LlamaIndex Integration for LlamaIndex usage.

Security Levels

Supported LLM Providers

---

🛠️ Create Custom Skill

Each Skill is a directory with a SKILL.md:

my-skill/
├── SKILL.md           # Skill metadata (required)
├── scripts/main.py    # Entry script
├── references/        # Reference documents (optional)
└── assets/            # Resource files (optional)

---

📦 Crates Architecture

SkillLite is a Cargo workspace of focused, composable crates. Each crate has a single responsibility and can be compiled independently.

skilllite/                         Dependency Flow
├── Cargo.toml                     ────────────────────────────
├── skilllite/  (main binary)      skilllite (CLI entry point)
│                                    ├── skilllite-commands
└── crates/                          │     ├── skilllite-evolution ──┐
    ├── skilllite-core/              │     ├── skilllite-sandbox ────┤
    ├── skilllite-sandbox/           │     └── skilllite-agent (opt) │
    ├── skilllite-evolution/         ├── skilllite-agent             │
    ├── skilllite-executor/          │     ├── skilllite-evolution   │
    ├── skilllite-agent/             │     ├── skilllite-sandbox     │
    ├── skilllite-commands/          │     └── skilllite-executor    │
    ├── skilllite-swarm/             ├── skilllite-swarm             │
    ├── skilllite-artifact/          ├── skilllite-artifact          │
    └── skilllite-assistant/         └───────────┬──────────────────┘
                                          skilllite-core (foundation)

Two independently deliverable binaries: skilllite (full: evolution + agent + sandbox) and skilllite-sandbox (lightweight: sandbox + MCP only, ~3.6 MB). The sandbox has zero dependency on the agent or evolution crates — other frameworks (LangChain, AutoGen, CrewAI, etc.) can embed it directly via CLI, MCP, or as a Rust crate.

SDK & Integrations

• python-sdk (pip install skilllite) — Thin bridge (~770 lines of Python under python-sdk/skilllite/), zero runtime deps
• langchain-skilllite (pip install langchain-skilllite) — LangChain / LangGraph adapter

---

🤝 Upstream Contributions

SkillLite’s sandbox hardening experience was contributed to ZeroClaw via issue #4812 and adopted in PR #4821, improving its native sandbox security posture (seccomp, capability dropping, fail-closed backend selection).

Lockdown networking for MCP-style stacks was contributed to ai-jail in PR #16: repeatable --allow-tcp-port / config allow_tcp_ports can permit outbound TCP to listed ports while staying in lockdown (Landlock V4 ConnectTcp rules when the network namespace is shared), with behavior unchanged when no ports are configured.

---

📄 License

MIT — See THIRD_PARTY_LICENSES.md for third-party details.

📚 Documentation

• Pick your path — Sandbox/MCP (recommended) vs full stack vs optional desktop
• Assistant split architecture — How the desktop app can live in its own repo (L1/L2/L3, migration phases)
• Getting Started — Installation and quick start guide
• Channel and Gateway — Inbound webhook, SKILLLITE_CHANNEL_*, Assistant (EN); 中文
• Changelog — Version history and upgrade notes
• Environment Variables Reference — Complete env var documentation
• Architecture — Project architecture and design
• Architecture Comparison — Claude Code vs OpenClaw vs OpenCode vs SkillLite（中文）
• Contributing Guide — How to contribute