skrun

---

🎯 Why Skrun?

You shipped an AI capability. It works on your machine. But every user, every customer, every new model brings new plumbing.

Skrun is the open agent runtime. Turn your skill — declared as SKILL.md, AGENTS.md, or your own format — into a POST /run endpoint. Without building your own agent loop. Without picking a vendor. Without locking your users behind a wall.

Any model. Any cloud. BYOK. MIT. Your skill stays portable.

What you get

• ✅ Your skill stays in your repo, in the format you choose. Skrun is a deployment target — your repo stays the source of truth.
• ✅ Compatible with the Agent Skills open standard (SKILL.md) and AGENTS.md (Linux Foundation). Your existing skill works.
• ✅ Users bring their own LLM keys. You're never on the hook for their costs.
• ✅ Self-host on your infrastructure (Node 20+, SQLite or Postgres). Self-hosting guide. Cloud (coming soon).
• ✅ MIT. Multi-model: Claude, GPT, Gemini, Mistral, Groq, Grok, Ollama.
• ✅ Wrap existing scripts gradually. No big-bang rewrite required.

Skrun vs vendor runtimes

	Skrun	CMA / GEAP / Vendor runtimes
Models	Claude, GPT, Gemini, Mistral, Groq, Grok + any OpenAI-compatible endpoint (DeepSeek, Kimi, Qwen, Ollama, vLLM…)	One provider only
Deployment	Self-hosted (Node + SQLite/Postgres) or our cloud (coming soon)	Vendor cloud only
Format	SKILL.md (agentskills.io, 40+ platforms), AGENTS.md (Linux Foundation), or your own	Proprietary
Streaming	SSE + async webhooks	Varies
License	MIT	Closed
Auth	GitHub OAuth + API keys — multi-tenant namespaces	Vendor console only
LLM keys	Bring your own keys	Vendor billing only

---

🏗️ Use Cases

🚀 For OSS skill maintainers — close the issues you can't answer today

You wrote changelog-generator (or research-to-brief, or incident-postmortem). It works in Claude Code. Stars are climbing. Then someone opens issue #34: "How do I run this from a CI pipeline?" Issue #41: "Can I integrate this with Linear?" Issue #58: "My status-page automation needs this."

Today you respond: "Sorry, this is a SKILL.md — you need Claude Code installed." Half abandon.

With Skrun: skrun deploy, you reply with a curl command. Issue closed in 5 minutes instead of 3 hours of setup. The drop-off between "starred it" and "actually running it" disappears.

🛠️ For internal AI platforms — visibility and standardization without rewriting

Your team has accumulated 12 LLM-powered scripts in 2 years. Each engineer rolled their own. One left last week — three of his scripts are crashing silently. Your LLM bill went 5x without explanation. The board asked twice "what's our AI strategy?" — you don't have one.

With Skrun: wrap existing scripts gradually as skills (or AGENTS.md, or your own format). No big-bang rewrite. One dashboard for all AI calls — cost per feature, failure modes, ownership. Your team standardizes on one declarative format. New engineers read a manifest in 30 seconds instead of reverse-engineering 800 lines.

🎯 For freelance & agencies — stop bricolating per-client AI deliveries

Each new client means 2-3 weeks of build. You glue Express + Anthropic SDK + Vercel for each delivery. The plumbing is identical 70% of the time. Worse: when a client wants to switch from Anthropic to OpenAI 3 months later, you're back rewriting auth + retry + fallback logic.

With Skrun: same skill format, deploy per client. Model swap is a YAML edit. Your client gets a stable POST /run endpoint they own — they can host on their infra, swap models, take over anytime. You ship the skill, not a server you maintain.

---

💬 What would you deploy?

What skill would you turn into an API tomorrow? What's missing in your current agent setup?

Tell us in Discussions — we read every post, and it shapes what we build next.

---

🚀 Quick Start

npm install -g @skrun-dev/cli

skrun init --from-skill ./my-skill        # or: skrun init my-agent
skrun deploy -m "initial release"         # build + push + get your API URL
skrun verify dev/my-skill@1.0.0           # admin step — auto-admin in local dev
skrun run dev/my-skill -i '{"query":"analyze this"}'

That's it. Your agent is verified, callable via the CLI, and reachable as a POST /run HTTP endpoint:

curl -X POST http://localhost:4000/api/agents/dev/my-skill/run \
  -H "Authorization: Bearer dev-token" \
  -H "Content-Type: application/json" \
  -d '{"input": {"query": "analyze this"}}'

dev-token is for local development. In production, authenticate via GitHub OAuth or API keys — your GitHub username becomes your namespace, and a separate admin role gates skrun verify.

→ 10-minute tutorial · Concepts · API reference

---

📊 Dashboard

Every Skrun registry ships with a full operator dashboard at /dashboard. No separate install, no extra env var.

• Home — workspace stats, 24h/7d toggles, recent activity, top agents.
• Agents — sortable list with run counts, token usage, verification status.
• Agent detail — per-agent metrics, versions with notes, metadata, try-it curl.
• Runs — every execution across all agents, filterable by agent/ID/status/model.
• Run detail — full I/O, tokens, cost, model, event timeline (tool calls, LLM calls).
• Playground — call any agent interactively, watch SSE events live, save outputs.
• Settings — profile + API keys (sk_live_*) with one-shot reveal and revocation.

→ Screenshot tour of all 7 pages

---

📦 SDK

npm install @skrun-dev/sdk

import { SkrunClient } from "@skrun-dev/sdk";

const client = new SkrunClient({
  baseUrl: "http://localhost:4000",
  token: "dev-token",
});

// Sync — get the result
const result = await client.run("dev/code-review", { code: "const x = 1;" });
console.log(result.output);

// Stream — real-time events
for await (const event of client.stream("dev/code-review", { code: "..." })) {
  console.log(event.type); // run_start, tool_call, llm_complete, run_complete
}

// Async — fire and forget with webhook callback
const { run_id } = await client.runAsync("dev/agent", input, "https://your-app.com/hook");

// Pin a specific agent version — reproducible, no silent drift
const pinned = await client.run("dev/code-review", input, { version: "1.2.0" });
console.log(pinned.agent_version); // "1.2.0" — always echoed back

// Push with a note (like a git commit message)
await client.push("dev/code-review", bundle, "1.3.0", { message: "Added retry logic" });

9 methods: run, stream, runAsync, push, pull, list, getAgent, getVersions, verify. Zero runtime dependencies, Node.js 20+.

---

✨ Features

Feature	Description
🤖 Multi-model	6 built-in providers (Anthropic, OpenAI, Google, Mistral, Groq, xAI) + any OpenAI-compatible endpoint (DeepSeek, Kimi, Qwen, Ollama, vLLM…) — with automatic fallback
🔧 Tool calling	Local scripts (scripts/) + MCP servers (npx) — same ecosystem as Claude Desktop
💾 Stateful	Agents remember across runs via key-value state
📡 Streaming	SSE real-time events (run_start → tool_call → run_complete) + async webhooks
📦 Typed SDK	npm install @skrun-dev/sdk — run(), stream(), runAsync() + 6 more methods
📊 Operator Dashboard	Web UI at /dashboard — agents, runs, stats, settings, integrated playground with SSE streaming
📖 Interactive API docs	OpenAPI 3.1 schema + Scalar explorer at GET /docs
🔐 Production auth	GitHub OAuth login + API keys (sk_live_*) + multi-tenant namespaces
🗄️ Persistent storage	Pluggable database — SQLite for local dev (zero-config, file-based), Supabase PostgreSQL for production
🔑 Caller keys	Users bring their own LLM keys via X-LLM-API-Key — zero cost for operators
✅ Agent verification	Verified flag controls script execution — safe for third-party agents
📌 Version pinning + notes	Pin a specific agent version per call (version: "1.2.0") or attach a note at push (-m "...") — reproducible integrations, visible changelog
🌍 Environment separation	Agent behavior (model, tools) separated from runtime environment (networking, timeout, sandbox). Per-run overrides via POST /run body
📁 Files API	Unified /api/files namespace for both directions — upload binary inputs (image/PDF/audio) via , download agent-produced artifacts via