skrun

Turn any Agent Skill (SKILL.md) into a callable API via POST /run. Multi-model, stateful, open source.

Quick Start

npm install -g @skrun-dev/cli

# Import an existing skill → deploy → call
skrun init --from-skill ./my-skill
skrun deploy

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

Get Started

• Create a new agent
• Import an existing skill
• Develop & test locally
• Deploy

Create a new agent

skrun init my-agent
cd my-agent
# Creates SKILL.md (instructions) + agent.yaml (config)

Import an existing skill

skrun init --from-skill ./path-to-skill
# Reads SKILL.md, asks 2-3 questions, generates agent.yaml

Develop locally

skrun dev
# ✓ Server running at http://localhost:3000
# POST /run ready — watching for changes...

skrun test
# ✓ basic-test (output.score >= 0)
# 1 passed, 0 failed

Deploy

skrun deploy
# ✓ Validated → Built → Pushed
# 🚀 POST http://localhost:4000/api/agents/you/my-agent/run

v0.1 ships with a local runtime. Cloud deploy is on the roadmap — the architecture is ready (RuntimeAdapter interface).

Key Concepts

• Agent Skills — SKILL.md standard, compatible with Claude Code, Copilot, Codex
• agent.yaml — Runtime config: model, inputs/outputs, permissions, state, tests
• POST /run — Every agent is an API. Typed inputs, structured outputs.
• Multi-model — Anthropic, OpenAI, Google, Mistral, Groq with automatic fallback
• Stateful — Agents remember across runs via key-value state
• Tool calling — Two approaches: CLI tools (scripts/ — write your own, bundled with the agent) and MCP servers (npx — standard ecosystem, same as Claude Desktop)

Caller-provided API Keys

By default, POST /run uses the server's LLM API keys (from .env). You can instead provide your own keys per request via the X-LLM-API-Key header:

curl -X POST http://localhost:4000/api/agents/dev/code-review/run \
  -H "Authorization: Bearer dev-token" \
  -H "Content-Type: application/json" \
  -H 'X-LLM-API-Key: {"anthropic": "sk-ant-your-key"}' \
  -d '{"input": {"code": "function add(a,b) { return a + b; }"}}'

The header value is a JSON object mapping provider names to API keys. Accepted providers: anthropic, openai, google, mistral, groq.

Key priority: caller key > server key > 401 error. If the caller key fails (invalid, quota exceeded), the error is returned directly — no fallback to server keys.

Security: caller keys are never logged, stored, or returned in responses. Use HTTPS in production.

Demo Agents

All examples use Google Gemini Flash by default. Change the model section in agent.yaml to use any supported provider.

Try an example

# 1. Start the registry
cp .env.example .env          # add your GOOGLE_API_KEY
pnpm dev:registry              # keep this terminal open

# 2. In another terminal
skrun login --token dev-token
cd examples/code-review
skrun build && skrun push

# 3. Call the agent
curl -X POST http://localhost:4000/api/agents/dev/code-review/run \
  -H "Authorization: Bearer dev-token" \
  -H "Content-Type: application/json" \
  -d '{"input": {"code": "function add(a,b) { return a + b; }"}}'

Windows (PowerShell): use curl.exe instead of curl, and use @input.json for the body.

CLI

Full CLI reference →

Documentation

• API reference
• agent.yaml specification
• CLI reference
• Contributing

Contributing

git clone https://github.com/skrun-dev/skrun.git
cd skrun
pnpm install && pnpm build && pnpm test

See CONTRIBUTING.md for conventions and setup.

License

MIT