🛡️ Skarn

A fast, OS-sandboxed Model Context Protocol gateway with an embedded Code Mode engine and shell-output token compression — in a single Rust binary.

Cut your agent's API bill while physically stopping it from wiping your disk or exfiltrating your secrets.

---

Why

Autonomous AI coding agents have three expensive, dangerous habits:

1. Token bloat — they pump raw cargo test / npm install output and hundreds of MCP tool schemas straight into the context window.
2. The MCP scaling wall — attach a few MCP servers and the model now carries the JSON Schemas of every tool on every single turn.
3. Remote code execution by design — letting an agent run shell commands or LLM-generated code is RCE on your machine.

Skarn is one binary that fixes all three:

• Aggregates your downstream MCP servers behind a tiny, constant tool surface (search / read_tool_docs / execute) using Code Mode — the model writes a short script that orchestrates tools in a sandbox, so megabyte intermediate payloads never reach the context window.
• Compresses shell output with declarative, per-tool filters — typically 70–90% fewer tokens, while guaranteeing errors and warnings survive.
• Sandboxes everything it executes with OS-native kernel primitives — Seatbelt on macOS, Landlock + seccomp on Linux, AppContainer on Windows — with no Docker, no daemon, no VM.

 ┌──────────────────────────── Skarn (one binary) ────────────────────────────┐
│ │
AI agent ─┼─▶ search / execute ──▶ Code Mode isolate ──▶ skarn.callTool() ──┐ │
(Claude │ (≈1k tokens, (QuickJS, hermetic, │ │ │
Code, │ not 30k) OS-sandboxed) ▼ │ │
Cursor…) │ ┌────────────┐ ┌────────────┐ │
│ compressed 15-token ◀── return summary ──┤ MCP client │… │ MCP client │ │
│ result, not a 15k (big data stays └─────┬──────┘ └─────┬──────┘ │
│ log dump inside the box) ▼ ▼ │
└────────────────────────────────────────────── Postgres MCP GitHub MCP ──────┘

Status

Skarn is young. The macOS (Seatbelt) and Linux (Landlock + seccomp) sandboxes are runtime-verified in CI on every push; Windows AppContainer is the least exercised backend so far. By design it runs untrusted, model-generated code, so please read SECURITY.md for the threat model and what is explicitly out of scope before you point a real agent at it. The most useful thing you can send right now is a bug report or an attempt to break the sandbox.

Install

# One line (macOS / Linux):
curl -fsSL https://rani367.github.io/Skarn/install.sh | sh
# Or with Cargo:
cargo install skarn

This installs the skarn binary.

Quickstart

# 1. Scaffold a config and see integration snippets
skarn init
# 2. Check which kernel sandbox is active on your machine
skarn doctor
# 3. Point your agent at the gateway (Claude Code / Cursor / Windsurf):# add to your MCP config:# { "mcpServers": { "skarn": { "command": "skarn", "args": ["serve"] } } }# 4. (Optional) try a Code Mode script against your configured servers:
skarn exec --code 'return (await skarn.listTools()).length'# 5. (Optional) compress + sandbox the agent's shell commands directly:
skarn run --net deny -- cargo test# 6. (Optional) install shell completion (bash/zsh/fish/powershell):# skarn completions zsh > ~/.zfunc/_skarn# Then add `fpath+=~/.zfunc` and `compinit` to your .zshrc

Downstream servers can be local (transport = "stdio") or remote (transport = "http", Streamable HTTP with optional bearer auth) — see skarn.example.toml.

What you get

1. Code Mode — give the agent an API, not a schema dump

Instead of injecting every tool's schema, the gateway exposes three meta-tools. The model calls search() to find tools, then writes a short script and hands it to execute():

// The model writes this; Skarn runs it in a hermetic, OS-sandboxed isolate.constissues=awaitskarn.server("github").search_issues({q: "is:open label:bug"});conststale=issues.filter(i=>daysSince(i.updated_at)>90);// filtering happens HEREawaitskarn.server("slack").post_message({channel: "#triage",text: summarize(stale)});return{staleCount: stale.length};// only this returns to the model

The 1,000-row intermediate result never touches the context window.

Scenario	Classic MCP (input tokens)	Skarn Code Mode	Reduction
16 servers / 508 tools, multi-step task	~150,000	~2,000	~99%
Single 3-tool workflow	~20,700	~1,100	~95%

(Figures from the published Code Mode literature — see docs/adr/0001. Your mileage varies with catalog size.)

2. Token compression for raw shell output

skarn run --stats -- cargo test

Command	Raw tokens	Compressed	Reduction
cargo test	~25,000	~2,500	~90%
npm install	~16,000	~3,200	~80%
git diff	~10,000	~2,500	~75%
ls / tree	~2,000	~400	~80%

Errors, warnings, and failures are always kept — even rescued out of a truncated middle.

3. OS-native sandboxing — no Docker required

skarn run -- <cmd> confines the command to your project directory and denies network egress, enforced by the kernel:

Platform	Mechanism	Cold start
macOS	Seatbelt (sandbox_init)	< 5 ms
Linux	Landlock LSM + seccomp-bpf	< 5 ms
Windows	AppContainer + Job Object	< 10 ms

Compare to Docker's 200 ms+ cold start, root daemon, and per-seat licensing.

Code Mode execute gets the same protection: on macOS and Linux the gateway runs each script in a dedicated worker process that sandboxes itself (deny network, no workspace writes) before touching model-generated code, so an isolate escape still lands in a kernel-confined process. Configure it with isolation in skarn.toml (auto / worker / in_process).

How it fits your agent

• Claude Code / Codex CLI — run skarn hook for a PreToolUse hook that routes shell commands through skarn run (sandbox + compression, no prompt changes). See docs/integrations/claude-code.md.
• Cursor / Windsurf — set Skarn as an MCP server in the IDE config to get Code Mode + aggregation. See docs/integrations/cursor-windsurf.md.

Architecture

A Cargo workspace with strictly separated, independently usable crates:

Crate	Responsibility
skarn-sandbox	OS-native sandbox abstraction (Seatbelt / Landlock+seccomp / AppContainer)
skarn-compress	YAML-driven shell-output token compression
skarn-codemode	Hermetic QuickJS isolate + oxc TS-strip & AST validation + tool bridge
skarn-gateway	MCP server/client aggregation on the official rmcp SDK
skarn	The skarn CLI tying it all together

See the Architecture Decision Records for the engineering rationale.

Security

Skarn runs untrusted, model-generated code by design. Read SECURITY.md for the threat model, what is and isn't defended, and how to report vulnerabilities.

Building from source

git clone https://github.com/Rani367/Skarn
cd Skarn
cargo build --release # binary at target/release/skarn
cargo test --workspace # macOS sandbox is runtime-verified here

Requires Rust 1.95+.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

Website

The landing page lives at rani367.github.io/Skarn — a single-screen animated overview (a WebGL turbulent-flow hero with the headline numbers and one-line install). It also serves the installer, so the one-liner above (curl -fsSL https://rani367.github.io/Skarn/install.sh | sh) pulls from there.

The site source is in website/ (Vite + React) and deploys to GitHub Pages automatically via .github/workflows/pages.yml on every push that touches it.

License

Licensed under either of MIT or Apache-2.0 at your option.