skelm

Build secure, agentic, long-running workflows in TypeScript. Run them anywhere Node runs.

Default-deny permissions · Multi-backend agents (ACP, Opencode, Pi, OpenAI, Anthropic) · MCP-native · Self-hosted gateway · MIT

skelm is a TypeScript framework for authoring, running, and operating workflows — typed orchestrations that mix deterministic code, LLM inference, and full agent loops behind a single, secure, default-deny execution model. Every workflow is schedulable: fire one once, schedule it on cron, register a webhook, or let it run continuously inside a long-lived gateway service.

Status: early development. APIs are unstable until v1. Star the repo, open issues, contribute fixes — feedback now is the most valuable feedback.

Quick Start

npm install -g skelm
skelm init my-bot && cd my-bot
skelm run workflows/hello.workflow.ts

skelm init scaffolds a working project with one example workflow, an AGENTS.md agent definition, a SKILL.md skill package, and a skelm.config.ts with sensible default-deny permissions.

A workflow is a TypeScript module:

import { pipeline, code, agent } from 'skelm'
import { z } from 'zod'

export default pipeline({
  id: 'triage-issue',
  input:  z.object({ repo: z.string(), issueNumber: z.number() }),
  output: z.object({ label: z.string(), reasoning: z.string() }),
  steps: [
    code({
      id: 'fetch',
      run: async (ctx) => {
        const res = await fetch(`https://api.github.com/repos/${ctx.input.repo}/issues/${ctx.input.issueNumber}`)
        return await res.json()
      },
    }),
    agent({
      id: 'classify',
      backend: 'anthropic',
      agentDef: './agents/triager',
      skills:  ['github-readonly'],
      mcp:     [{ id: 'gh', transport: 'stdio', command: 'mcp-github' }],
      permissions: {
        allowedTools:      ['gh.add_label'],
        allowedMcpServers: ['gh'],
        allowedSkills:     ['github-readonly'],
        networkEgress:     { allowHosts: ['api.github.com'] },
        fsRead:            ['./'],
        fsWrite:           [],
      },
      prompt: (ctx) => `Triage this issue:\n${JSON.stringify(ctx.steps.fetch)}`,
      output: z.object({ label: z.enum(['bug','feature','duplicate']), reasoning: z.string() }),
      maxTurns: 8,
    }),
  ],
})

# Run it once
skelm run workflows/triage-issue.workflow.ts --input '{"repo":"acme/x","issueNumber":42}'

# Or schedule it via webhook
skelm schedule add workflows/triage-issue.workflow.ts --webhook /webhooks/issue-events

# Stand up the long-running gateway
skelm gateway start

Why skelm?

If you have built any of the following with hand-rolled scripts, you have felt skelm-shaped pain:

• A coding assistant reachable on chat that opens PRs in a persistent repo workspace.
• A queue worker that watches Jira and tries to ship the ticket.
• An email-triage agent that classifies, summarizes, and journals decisions you can audit.
• A nightly digest that fans out, enriches with an LLM, and posts to Slack.
• An HTTP endpoint that runs a typed workflow with three deterministic steps and one LLM call.

skelm gives you one substrate for all five.

Three tenets, in this order

1. Security. Default-deny everywhere. A backend that cannot enforce a declared permission fails at step start instead of bypassing it. The gateway is the single trust boundary; nothing privileged happens outside it.
2. Maintenance. A small core, a narrow public surface, no DSL. Workflows are TypeScript modules.
3. Robustness. Typed context end-to-end. Explicit error semantics. Deterministic event log. Durable wait/resume. Persistent state and per-agent workspaces that survive restarts.

These outrank everything else. We will ship a smaller framework that is secure, maintainable, and robust before we ship a larger one that is not.

How it compares

Packages

Documentation

Customer-facing docs live under docs/ — quickstart, full CLI/API/HTTP reference, deployment guides, recipes for common workflow shapes.

• Quickstart: docs/quickstart/index.md
• Provider architecture: docs/backends/README.md
• Guides: docs/guides/ — testing, plugins, authoring tips
• Recipes: docs/recipes/ — complete workflow examples
• Reference: docs/reference/ — API, CLI, HTTP, configuration schemas
• Deployment: docs/deployment/ — systemd, reverse proxy, Postgres, secrets
• Contributors: AGENTS.md — workflow, code style, testing expectations
• Changelog: CHANGELOG.md — version history
• Security policy: SECURITY.md — reporting vulnerabilities

Roadmap

• M1 — Core runtime + CLI. Workflow authoring, three step kinds, three in-tree backends (copilot-acp, openai, anthropic), full permission enforcement, SQLite run store.
• M2 — Control flow + workspaces + state. parallel/forEach/branch/loop/wait, per-agent workspaces, persistent KV state, agent definition markdown loader, introspection commands.
• M3 — Gateway, audit, scheduler, debug. Long-running gateway service, HTTP + SSE, audit log, secrets driver, scheduler with cron/interval/webhook/poll/queue triggers, systemd user unit installer, debug breakpoints.
• M4 — Integrations + multi-backend support + Postgres. Curated @skelm/integrations, OAuth setup, OpenAI-compatible HTTP surface, additional agent backends, cost/quality routing, Postgres run store, vault secrets, distributed dedupe.

Community

• GitHub Discussions — questions, ideas, show & tell
• Issues — bug reports and feature requests
• Contributing — PRs welcome

The framework dogfoods itself: skelm's own pre-merge review and unit-test generation run as skelm workflows under pipelines/internal/. Reading those is a good way to learn the API and see how the security tenet works in practice.

Author

Scott Glover — [email protected]

License

MIT. Copyright © Scott Glover.

If you build something interesting on skelm, we want to hear about it — open an issue with the showcase label.