v0.8.0 — Multi-Tenancy & Per-Version Trust

Highlights

• Registry reads filter by ownership — GET /api/agents, /:ns/:name, /:ns/:name/versions, /:ns/:name/stats, and /pull* now require auth and return 404 to non-owner non-admin callers (indistinguishable from "doesn't exist"). Running an agent (POST /run) stays cross-namespace. SDK + CLI client methods updated to send the header.
• Per-version verification gate — POST /run refuses unverified versions with 403 AGENT_NOT_VERIFIED before any LLM call. Verify/unverify is admin-only via PATCH /:versions/:version/verify (and skrun verify / skrun unverify / SkrunNotVerifiedError typed in the SDK). Pinned callers are protected — pushing a new version doesn't touch prior verified versions.
• Slug-only agent.yaml.name — was <namespace>/<slug>; the registry now assigns the namespace from auth at push time. CLI --namespace flag and interactive prompt gone. Dashboard Import dialog uses explicit form fields (fixes a long-standing filename mis-parse on multi-hyphen slugs).
• skrun whoami + skrun run + run-output validation + downloadable artifacts — whoami prints CLI identity. run <ns>/<name>[@<v>] invokes an agent end-to-end (closing the long-standing gap with push). Runtime validates final LLM output against the declared schema (one repair retry on mismatch). Dashboard renders a Files block on playground + run-detail with per-file Download.
• Cross-tenant run leakage fixed — GET /api/runs filters by user id (was instance-wide). GET /api/runs/:id returns 403 for non-owners. Latent on single-user self-host; would have shipped broken on cloud.
• IPv6 SSRF + symlink + gzip-bomb defenses + spawned-script env allowlist — network allowlist now blocks IPv4-mapped IPv6 (::ffff:*) and link-local (fe80:*). Bundle decompression capped at 50 MB. Output collection skips symlinks. Agent script processes get a strict env allowlist instead of the full process.env.

Breaking

• Registry GET endpoints require auth — dev-token self-host unaffected (auto-admin); OAuth and sk_live_* callers must pass Authorization: Bearer <token>.
• agent.yaml.name is slug-only — migration: name: dev/email-drafter → name: email-drafter.
• Verification is per-version + admin-only — legacy PATCH /api/agents/:ns/:name/verify removed. SDK client.verify() → client.verifyVersion(). Existing verified=true rows reset on upgrade.
• POST /run returns 403 AGENT_NOT_VERIFIED for unverified versions. The old soft agent_not_verified_scripts_disabled warning is gone.
• File-content endpoints require auth + ownership — GET /api/files/:id, /content, and GET /api/runs/:run_id/files/:filename were public before.
• WEBHOOK_SIGNING_KEY is now required. The hardcoded fallback is removed; runtime throws if unset.
• CORS_ORIGIN is required in production. When NODE_ENV=production, API fails fast at startup.

Migration

• Set WEBHOOK_SIGNING_KEY and (in production) CORS_ORIGIN in your environment — see .env.example.
• Update agent.yaml: drop the namespace prefix from name.
• Re-verify each version after upgrade (skrun verify <ns>/<name>@<version> as admin).
• Update SDK usage: client.verify() → client.verifyVersion(); catch SkrunNotVerifiedError instead of string-comparing err.code.
• Supabase self-hosters: migrations 008 (add per-version verified) + 009 (drop legacy agents.verified) apply automatically; SQLite users get FK + UNIQUE constraint upgrades on first start.

Stats

• 1222 unit + integration tests pass (was 993 at v0.7.0)
• 101 E2E in-memory + 57/57 live (multi-provider)
• 21 security findings closed (audit/001 pre-cloud-hardening) + 7 demo-robustness bugs closed (audit/002)
• OpenAPI 3.1 spec at 0.8.0

Install

```bash
npx @skrun-dev/cli@0.8.0 --version

or

npm i -g @skrun-dev/cli@0.8.0
```

Full changelog: CHANGELOG.md

v0.7.0 — Multimodal & Native Caching

Highlights

• Multimodal inputs — agents accept images, PDFs, and audio directly via type: file in agent.yaml. Three transports: upload to /api/files (source: "id"), inline base64 (source: "data"), or HTTPS URL (source: "url"). The SDK auto-uploads Blob/File/Uint8Array.
• Native prompt caching — 30-90% input-token savings on repeated system + tools content. Automatic across Anthropic, OpenAI, Google Gemini, xAI Grok, and Groq. No agent.yaml change required. New usage.cache_read_tokens field; cost-tracking accuracy ±5% of provider invoice.
• Script dependency resolution — drop a package.json (Node) or requirements.txt / pyproject.toml (Python) at the bundle root. Skrun resolves deps on first run, caches at ~/.skrun/deps/<hash>/ for instant subsequent runs. Auto-detects pnpm/yarn/npm + uv/poetry lockfiles for reproducible installs. New skrun cache list/clear.
• Tool choice directives — tool_choice: <tool-name> to force a specific tool, required to force any tool, none to block, or per-tool required: true. Native translation across Anthropic, Gemini, OpenAI, xAI.
• xAI Grok 4.3 as 6th first-class provider — set XAI_API_KEY. Image input + text-only documents. $1.25/M input, $2.50/M output.
• Cache cost-savings on the dashboard — "Cost saved" tile on home (sparkline), `saved $X.XX` on run-detail, "Cache savings 7d" on agent-detail.
• Per-version delete endpoint — `DELETE /api/agents/:ns/:name/versions/:version` removes a single bad version without nuking the whole agent. 409 `LAST_VERSION` if it would orphan.

Breaking

None.

Migration

• Supabase self-hosters: run migration `004_add_cache_to_runs.sql` from `packages/api/src/db/migrations/` to add the new `runs.usage_cache_*` columns. SQLite users: auto-applied on startup.
• Existing agents continue to work unchanged — all new features are opt-in via `agent.yaml`.

Stats

• 993 tests pass (was 522 at v0.6.0)
• 38/38 live tests (multi-provider, including cache hit verification)
• 6 first-class providers (was 5)
• OpenAPI 3.1 spec at 0.7.0

Install

```bash
npx @skrun-dev/cli@0.7.0 --version

or

npm i -g @skrun-dev/cli@0.7.0
```

Full changelog: CHANGELOG.md

v0.6.0

Highlights

• Operator Dashboard at /dashboard — agents, runs, stats with sparklines, integrated playground with SSE streaming, API key management. Light/dark theme.
• GitHub OAuth + API keys — sign in with GitHub (your username = your namespace), or create sk_live_* keys for CI/programmatic access.
• Multi-tenant namespaces — push/verify/delete restricted to namespace owner. Running an agent stays public.
• Persistent local storage — SQLite by default (zero config). Agents, runs, and keys survive restarts. Optional Supabase for production.
• Version notes at push — skrun push -m "retry logic" attaches a note displayed in the dashboard like a git commit message.
• Eight new demo agents under agents/ — each produces a real downloadable artifact (PDF, XLSX, PPTX, ZIP, CSV, MD) and runs without any secondary API key. OSS workflows, team operations, analyst deliverables.
• New documentation — Concepts, Getting Started, Self-hosting.

Breaking

• On shared instances with OAuth configured, dev-token is no longer accepted — use OAuth or an API key.

Migration

• Folder rename examples/ → agents/ — update local scripts/bookmarks.
• .env.example now sets SKRUN_AGENTS_DIR=./agents as the dev default.
• Supabase self-hosters: run migrations 002_add_model_to_runs.sql and 003_add_version_notes.sql from packages/api/src/db/migrations/.

Stats

• 522 tests pass (443 unit + 79 E2E)
• OpenAPI 3.1 spec at /openapi.json — bumped to 0.6.0 with 7 new endpoints

Install

```bash
npx @skrun-dev/cli@0.6.0 --version

or

npm i -g @skrun-dev/cli@0.6.0
```

Full changelog: CHANGELOG.md

v0.5.0 — Cloud Foundation

v0.5.0 — Cloud Foundation

Four features preparing Skrun for cloud deployment and third-party agents.

Breaking

• permissions and runtime replaced by environment in agent.yaml — unified section for networking, filesystem, secrets, timeout, sandbox. Migration guide.

Added

• Environment separation — agent behavior (model, tools) cleanly separated from runtime environment (networking, timeout, sandbox). Per-run overrides via POST /run body. SDK RunOptions.environment.

• Bundle + MCP cache — repeated POST /run calls skip re-extraction and reuse MCP connections. Reconnect-on-error for dropped connections. Configurable via env vars (BUNDLE_CACHE_TTL, MCP_CACHE_TTL).

• Network allowlist (allowed_hosts) — agents declare which hosts they can reach. Empty = all blocked (safe default), glob patterns (*.github.com), ["*"] = unrestricted. Private IPs always blocked.

• Files API — agents produce files by writing to $SKRUN_OUTPUT_DIR. Download via GET /api/runs/:run_id/files/:filename. Configurable limits (FILES_MAX_SIZE_MB, FILES_MAX_COUNT, FILES_RETENTION_S).

Numbers

• 407 tests (324 unit + 55 E2E + 28 live)
• 5 npm packages at v0.5.0

Install

npm install @skrun-dev/sdk@0.5.0
npx @skrun-dev/cli@0.5.0 --version

Generated with Claude Code

v0.4.0 — Production-ready agent metadata

What's new

Breaking

• tools: in agent.yaml must now be objects — { name, description, input_schema } with JSON Schema draft-07 typing. The LLM receives the declared schema as the tool spec; arguments are validated (Ajv) before the script runs. See docs/agent-yaml.md.

Added

• Agent version pinning — pass version: "1.2.0" in the POST /run body to target a specific version. Response always echoes agent_version. Non-existent version returns 404 with available: [...] for recovery. SDK exposes { version } option on run(), stream(), runAsync().
• Structured JSON logging via pino — every log line is valid JSON with level, time, run_id, agent, agent_version. LOG_LEVEL env var (debug/info/warn/error) controls verbosity. createLogger exported from @skrun-dev/runtime.
• ToolConfigSchema, InputSchemaSchema exported from @skrun-dev/schema
• OpenAPI schema updated: version in request body, agent_version in response, VersionNotFoundResponse

Tests

354 tests green (279 unit + 50 E2E integration + 25 E2E live).

Install

```bash
npm install -g @skrun-dev/cli@0.4.0
npm install @skrun-dev/sdk@0.4.0
```

Full changelog: https://github.com/skrun-dev/skrun/blob/main/CHANGELOG.md

v0.3.0

What's New

SSE Streaming

Accept: text/event-stream on POST /run streams real-time events during agent execution: run_start, tool_call, tool_result, llm_complete, run_complete.

Async Webhook

webhook_url in POST /run body returns 202 Accepted immediately. Result delivered via POST callback with HMAC-SHA256 signature (X-Skrun-Signature).

TypeScript SDK (@skrun-dev/sdk)

Official typed client for Node.js 18+. Zero dependencies.

npm install @skrun-dev/sdk

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

const result = await client.run("dev/code-review", { code: "..." });
for await (const event of client.stream("dev/agent", { code: "..." })) { ... }

9 methods: run, stream, runAsync, push, pull, list, getAgent, getVersions, verify.

OpenAPI 3.1 + Interactive Docs

• GET /openapi.json — full API schema (import into Postman/Insomnia)
• GET /docs — Scalar interactive explorer with "Try it" functionality

Stats

• 314 tests (244 unit + 48 E2E + 22 live)
• 5 npm packages: @skrun-dev/schema, @skrun-dev/cli, @skrun-dev/runtime, @skrun-dev/api, @skrun-dev/sdk

Install

npm install -g @skrun-dev/cli
npm install @skrun-dev/sdk

v0.2.0

What's new

Features

• Agent verification — verified flag controls script execution. Non-verified agents run with LLM + MCP only. Operators verify via PATCH /verify. Dev-token bypasses for local dev.
• Caller-provided LLM keys — X-LLM-API-Key header on POST /run. Operators have zero LLM cost exposure.

Security

• Path traversal fix in bundle extraction — skip ../ and absolute paths, verify with resolve() + sep (thanks @hobostay)

Bug fixes

• Anthropic provider message ordering for tool results (thanks @hobostay)
• Tool call args: providers now pass original args instead of hardcoded {}

Tests

• 225 total tests (187 unit + 24 E2E integration + 14 E2E live)
• Centralized E2E test suite (pnpm test:e2e)
• Live E2E with auto-start registry (pnpm test:e2e:live)

Docs

• Full API reference (docs/api.md)
• CHANGELOG.md

npm: npm install @skrun-dev/cli@0.2.0

v0.1.1 — Initial Release

skrun v0.1.1

Deploy any Agent Skill as an API via POST /run.

Highlights

• 4 packages: @skrun-dev/schema, @skrun-dev/cli, @skrun-dev/runtime, @skrun-dev/api
• 10 CLI commands: init, init --from-skill, dev, test, build, deploy, push, pull, login, logs
• 5 LLM providers: Anthropic, OpenAI, Google, Mistral, Groq — with automatic fallback
• Tool calling: CLI tools (scripts/) and MCP servers (npx — same ecosystem as Claude Desktop)
• MCP multi-transport: stdio, Streamable HTTP, SSE
• Stateful agents: key-value state across runs
• 6 demo agents: code-review, pdf-processing, seo-audit, data-analyst, email-drafter, web-scraper

Quick Start

npm install -g @skrun-dev/cli
skrun init my-agent
skrun deploy

Links

• README
• agent.yaml spec
• CLI reference