# skein-js

> The open-source LangGraph Platform alternative for TypeScript (LangGraph Platform is now LangSmith Deployment). Host LangGraph.js graphs with the existing Agent Protocol, persistent threads, runs, streaming, approvals, and schedules. Choose Postgres/Redis for a shared server, or SQLite for a desktop app, CLI, daemon, or one Node owner. The CLI remains a drop-in replacement for the LangGraph CLI (`skein dev` ⇄ `langgraph dev`). Open source (Apache-2.0), with no license key or per-run bill. Not yet implemented: an `/mcp` endpoint.

skein-js implements LangChain's Agent Protocol, so the LangChain client ecosystem (`@langchain/langgraph-sdk`, `useStream`, Agent Chat UI, LangGraph Studio) works with an existing HTTP/SSE adapter. Terminal applications can call the protocol service directly. It reuses LangGraph execution and checkpointers; applications own models, tools, credentials, and recovery decisions. Every adapter accepts `{ config } | { deps }`: load a `langgraph.json`, or supply assembled protocol dependencies from memory, Postgres/Redis, or `@skein-js/local` with SQLite. SQLite supports Node 22/24, has one owner per file, and records abandoned attempts as failures without automatically replaying input.

Documentation: [skein.js.org](https://skein.js.org/). Guides below link to the site's Markdown pages.

Upstream references: [LangGraph.js overview](https://docs.langchain.com/oss/javascript/langgraph/overview), [LangGraph CLI](https://docs.langchain.com/langsmith/cli), and [Agent Server](https://docs.langchain.com/langsmith/agent-server).

## Getting started

- [Why skein-js](https://skein.js.org/why.md): The motivation — how teams end up needing an agent backend, the four real options (build it, LangGraph Platform, aegra, skein), the licensing detail, why leaving is deliberately one word, and who this isn't for.
- [Your first agent](https://skein.js.org/your-first-agent.md): From an empty directory to a deployed agent, assuming no LangGraph experience — scaffold, the four LangGraph concepts, add a model and a tool, ship.
- [Getting started](https://skein.js.org/getting-started.md): Guided walkthrough from zero to a running server, then to production (all three on-ramps).
- [Scaffolding a project](https://skein.js.org/scaffolding.md): `npm create skein-js@latest` — default ESLint/Prettier, supported Node versions, workspace registration, the Nx generator, tooling inheritance and caching, and the equivalent files by hand.
- [Agent skills](https://skein.js.org/agent-skills.md): Installable guidance for server and local application setup, SQLite embedding, and Nx/Turborepo task and cache integration.
- [Using skein-js](https://skein.js.org/using-skein.md): Terse consumer/agent cheat-sheet — install, the `{ config } | { deps }` seam, mount on each framework, call it.
- [Building blocks](https://skein.js.org/building-blocks.md): What an agent is made of, told as the story of what reality adds to a model-and-a-prompt — tools, control flow, concurrent messages, checkpoints and threads, long-term memory, approvals, streaming, deferred work, versioned config, telemetry and durability — and which of those are yours, LangGraph's, or skein's.
- [LangGraph essentials](https://skein.js.org/langgraph-essentials.md): The shallow dive on LangGraph itself — state and channels, reducers, nodes, edges, `.compile()`, prebuilt agents, tools, `interrupt()`, subgraphs, stream modes, and why you must let skein inject the checkpointer and store rather than constructing your own. Links out to the LangChain docs per concept.
- [Recipes](https://skein.js.org/recipes/index.md): Task snippets — coupled WhatsApp replies, decoupled email-to-WhatsApp routing, human-in-the-loop, memory, authentication providers, webhooks, and deploy.
- [Overview](https://skein.js.org/index.md): What skein is, why it exists, key features, and how to start or choose a deployment.
- [README](https://github.com/skein-js/skein-js/blob/main/README.md): The project introduction — purpose, key features, quick start, deployment paths, and links to guides and examples.

## Guides

- [Local apps and SQLite](https://skein.js.org/local-deployment.md): An optional deployment for Electron, Tauri, CLI apps, and daemons using the same Agent Protocol. Embedding, CLI selection, ownership, and crash behavior.
- [LangGraph CLI compatibility](https://skein.js.org/langgraph-cli-compat.md): Every `langgraph.json` field + the `skein` command mapping (`dev`/`up`/`build`/`dockerfile`).
- [Framework adapters](https://skein.js.org/adapters.md): Express, Fastify, NestJS, Next.js and Fetch — the standalone and mount-into-your-app entry for each, and what actually differs between them: mount path, CORS mechanism, JSON body cap, logger default, whether `/ok` exists, and what drains the run worker on shutdown.
- [Embedding a graph in code](https://skein.js.org/embedding.md): The in-code on-ramp — serve a compiled graph with no `langgraph.json` and no CLI.
- [Native access and BullMQ](https://skein.js.org/native-access.md): Authorized embedded calls, durable admission receipts, strict resume, retained results, external command/outcome queues and broker reconciliation.
- [Native access security](https://skein.js.org/native-access-security.md): Host authority, raw-query projection boundaries, Redis copies and retention, cancellation recovery and resource budgets.
- [Serving a graph as a plain endpoint](https://skein.js.org/serving-a-single-graph.md): The non-chat surface — `POST /invoke/:graph_id`, body-in / final-state-out, no threads or runs.
- [Agent Protocol surface](https://skein.js.org/agent-protocol.md): The REST + SSE endpoint inventory skein implements, plus the auth route→permission map.
- [Features](https://skein.js.org/features.md): "Can skein do X?" — every capability in one page, grouped by what you're trying to build, each linking out.
- [Runs](https://skein.js.org/runs.md): Picking a run mode (wait/stream/background/stateless/batch), all four multitask strategies, cancel vs rollback, run timeouts, and the defaults that differ from LangGraph.
- [Background jobs](https://skein.js.org/background-jobs.md): Fire-and-forget work — stateless background runs, hearing the result by webhook, idempotent submission, batching and scheduling, and why a failed job is not retried.
- [State, context & persistence](https://skein.js.org/state-and-context.md): The core building block — the four bags a run carries (input vs context vs config.configurable vs metadata), what checkpoints make possible, short-term vs long-term memory, what survives a restart, and the reserved configurable keys the server strips.
- [Threads](https://skein.js.org/threads.md): Conversations that persist — get-or-create by your own key, reading state and history, time travel (fork from a checkpoint), importing an existing conversation, pruning and thread TTL.
- [Human-in-the-loop](https://skein.js.org/human-in-the-loop.md): Pausing a run with `interrupt()` and resuming it with a command, building an approvals queue, and the checkpointer requirement that silently no-ops resume without it.
- [Assistants](https://skein.js.org/assistants.md): Versioned graph configuration — several configs of one graph, immutable versions on every PATCH, one-call rollback, and schema/graph introspection.
- [Run-completion webhooks](https://skein.js.org/webhooks.md): Durable outbound delivery — the transactional guarantee, the three retry tiers, Stripe-format signing with a shipped verifier, listing and replaying deliveries, and what is stored and for how long.
- [Workflows and channels](https://skein.js.org/channels.md): Connect authenticated provider sources and durable destinations through a LangGraph workflow.
- [Streaming](https://skein.js.org/streaming.md): LangGraph stream modes mapped onto Agent Protocol SSE, with cross-instance fan-out.
- [Errors & logging](https://skein.js.org/errors-and-logging.md): What happens when a graph throws — the `RunError` payload, `exposeErrorStacks`, the `Logger` interface, and the `skein dev` failure block.
- [LangGraph compatibility](https://skein.js.org/langgraph-compatibility.md): Dated verification scope and intentional Agent Server differences.
- [React SDK / useStream](https://skein.js.org/react-sdk.md): Frontend compatibility — `@langchain/langgraph-sdk` and `useStream` over SSE.
- [Storage](https://skein.js.org/storage.md): `SkeinStore`, memory/SQLite/Postgres selection, pgvector semantic search, upstream checkpointers, and `getStore()` in a graph.
- [Runs & Redis](https://skein.js.org/runs-and-redis.md): The run engine, the queue, and cross-instance streaming with Redis.
- [Observability](https://skein.js.org/observability.md): Tracing and metrics — the `TelemetrySink` seam, LangSmith thread grouping, PostHog `$ai_generation` analytics, OpenTelemetry spans/metrics, and guides for Langfuse, Braintrust, Sentry, and Datadog/Grafana/Honeycomb.
- [Deploy anywhere](https://skein.js.org/deploy.md): Deploying the `skein build` Docker image on any platform — Postgres/Redis setup, ports, the `/ok` health probe, connection-pool sizing, SIGTERM draining, SSE through proxies, and the multi-instance caveats.
- [Performance & memory](https://skein.js.org/performance.md): What uses memory, sizing for 256Mi–4Gi, every tuning knob in one table, SSE backpressure and drop/recovery semantics, query bounds, and a symptom→knob triage table.
- [Profiling](https://skein.js.org/profiling.md): How to measure rather than guess — benchmarks vs profilers vs telemetry, reading percentiles and memory layers, Node/Bun/Deno profiling recipes, five diagnostic exercises, and the benchmark traps that invalidate results.
- [Deploy on Google Cloud Run](https://skein.js.org/deploy-cloud-run.md): Artifact Registry, Cloud SQL or a hosted Postgres, Secret Manager, and why background runs need `--no-cpu-throttling --min-instances=1`.
- Per-platform guides also cover [Railway](https://skein.js.org/deploy-railway.md), [Fly.io](https://skein.js.org/deploy-fly.md), [Render](https://skein.js.org/deploy-render.md), [AWS App Runner and ECS Fargate](https://skein.js.org/deploy-aws.md), [Kubernetes](https://skein.js.org/deploy-kubernetes.md), [a plain VPS](https://skein.js.org/deploy-vps.md), and [what does and doesn't work on Vercel/serverless](https://skein.js.org/deploy-serverless.md).
- [Bundling skein](https://skein.js.org/bundling.md): For when you own the bundler (rspack/webpack/esbuild/Next.js) — skein is ESM-only but `require()`-resolvable, `@langchain/langgraph-api` + `@typescript/vfs` must stay external, everything else bundles cleanly.
- [The skein console](https://skein.js.org/console.md): Test a graph with Chat or JSON, inspect activity and state, diagnose failures, and try approval or checkpoint paths.
- [Console setup reference](https://skein.js.org/console-reference.md): Connections, authentication, production enablement, manual mounting, and advanced run options.
- [Testing your project](https://skein.js.org/testing-your-project.md): Run generated graph tests, add an SDK smoke test, and check persistence and interrupt/resume.
- [Building a custom adapter](https://skein.js.org/building-an-adapter.md): Put skein on any HTTP framework via the transport-neutral handler table.

## API by package

- [@skein-js/core](https://github.com/skein-js/skein-js/tree/main/packages/core#readme): The shared contract — Agent Protocol wire types + `SkeinStore`/queue/bus/auth interfaces + `SkeinHttpError`.
- [@skein-js/agent-protocol](https://github.com/skein-js/skein-js/tree/main/packages/agent-protocol#readme): The framework-agnostic engine — run engine, handler table, SSE. `createProtocolRuntime`, `skeinRoutes`.
- [@skein-js/console](https://github.com/skein-js/skein-js/tree/main/packages/console#readme): The skein console — the compiled web UI plus `resolveConsoleRequest`/`consoleAssetHeaders`. No runtime dependencies; the SPA is embedded as string constants.
- [@skein-js/config](https://github.com/skein-js/skein-js/tree/main/packages/config#readme): `langgraph.json` parser + graph loader. `loadConfig`.
- [@skein-js/server-kit](https://github.com/skein-js/skein-js/tree/main/packages/server-kit#readme): Shared adapter building blocks. `embedInMemoryGraphs`, in-memory runtime, CORS.
- [@skein-js/local](https://github.com/skein-js/skein-js/blob/main/packages/local/README.md): `embedSqliteGraphs` assembles SQLite resources, queue, and upstream checkpoints. The host owns process and worker lifetime.
- [@skein-js/storage-sqlite](https://github.com/skein-js/skein-js/blob/main/packages/storage-sqlite/README.md): `openSqliteStorage` supplies the resource store, durable queue, borrowed connection, and disposal for one database file.
- [@skein-js/runtime](https://github.com/skein-js/skein-js/tree/main/packages/runtime#readme): Assembles production deps. `buildRuntime` (from `langgraph.json`), `embedPostgresGraphs` (from graphs in code).
- [@skein-js/langsmith](https://github.com/skein-js/skein-js/tree/main/packages/telemetry-langsmith#readme): LangSmith tracing — run identity and Threads grouping. `createLangSmithTelemetry`.
- [@skein-js/posthog](https://github.com/skein-js/skein-js/tree/main/packages/telemetry-posthog#readme): PostHog analytics — run lifecycle events plus `$ai_generation`. `createPostHogTelemetry`.
- [@skein-js/otel](https://github.com/skein-js/skein-js/tree/main/packages/telemetry-otel#readme): OpenTelemetry spans + metrics for runs, API-only so any OTLP backend works. `createOtelTelemetry`.
- [@skein-js/express](https://github.com/skein-js/skein-js/tree/main/packages/server-express#readme): Express adapter — `createExpressServer`, `skeinRouter` (the reference adapter).
- [@skein-js/fastify](https://github.com/skein-js/skein-js/tree/main/packages/server-fastify#readme): Fastify adapter — `createFastifyServer`, `skeinPlugin`.
- [@skein-js/nestjs](https://github.com/skein-js/skein-js/tree/main/packages/server-nestjs#readme): NestJS adapter — `SkeinModule.forRoot`, `createNestServer`.
- [@skein-js/nextjs](https://github.com/skein-js/skein-js/tree/main/packages/server-nextjs#readme): Next.js adapter — `createSkeinRouteHandlers` (App Router), `createSkeinPagesHandler` (Pages Router).
- [@skein-js/fetch](https://github.com/skein-js/skein-js/tree/main/packages/server-fetch#readme): Web-standard Fetch transport — `createSkeinFetchServer`, plus `startBunServer` / `startDenoServer`. The production path on Bun and Deno; the only adapter that caps request bodies itself.
- [@skein-js/storage-memory](https://github.com/skein-js/skein-js/tree/main/packages/storage-memory#readme): In-memory `SkeinStore` + queue (dev/tests).
- [@skein-js/storage-postgres](https://github.com/skein-js/skein-js/tree/main/packages/storage-postgres#readme): Postgres `SkeinStore` + pgvector; reuses `PostgresSaver`.
- [@skein-js/redis](https://github.com/skein-js/skein-js/tree/main/packages/runtime-redis#readme): Redis run queue + cross-instance pub/sub streaming.
- [skein-js (CLI)](https://github.com/skein-js/skein-js/tree/main/packages/cli#readme): The drop-in CLI — `dev` / `up` / `build` / `dockerfile` / `import-langgraph`.
- [create-skein-js](https://github.com/skein-js/skein-js/tree/main/packages/create-skein-js#readme): The scaffolder — `npm create skein-js@latest my-agent`. Default ESLint/Prettier and Node 24 guidance; run once instead of adding it as a project dependency.
- [@skein-js/nx](https://github.com/skein-js/skein-js/tree/main/packages/nx): The application generator for Nx 23.2.1 through 23.x, with integrated/package layouts, storage choices, and default tooling.

## Examples

- [Daybook — Electron](https://github.com/skein-js/skein-js/tree/main/examples/desktop-electron): Meeting notes, model tools, streamed conversation, and recaps saved after review.
- [Reading Room — Tauri](https://github.com/skein-js/skein-js/tree/main/examples/desktop-tauri): A document library with source excerpts, reading briefs, and persistent conversation.
- [Dayplan — CLI](https://github.com/skein-js/skein-js/tree/main/examples/local-cli): A daily planner using local tasks, earlier plans, and approval before saving.
- [express-basic](https://github.com/skein-js/skein-js/tree/main/examples/express-basic): Zero-setup `echo` + a model-backed `agent` graph from one `langgraph.json`.
- [embed-graph](https://github.com/skein-js/skein-js/tree/main/examples/embed-graph): In-code embedding with no `langgraph.json` (`embedInMemoryGraphs` + `{ deps }`).
- [chat-app](https://github.com/skein-js/skein-js/tree/main/examples/chat-app): Flagship — a Gemini research assistant (thinking + web search + long-term memory) with a Next.js + shadcn UI.
- [gemini-chat](https://github.com/skein-js/skein-js/tree/main/examples/gemini-chat): Model-backed end-to-end — a Gemini ReAct agent streamed into a browser.
- [migrated-langgraph](https://github.com/skein-js/skein-js/tree/main/examples/migrated-langgraph): The drop-in proof — a stock LangGraph project run under `skein dev`.
- [Framework adapters](https://github.com/skein-js/skein-js/tree/main/examples): fastify-basic/-app, nestjs-basic/-app, nextjs-basic/-app (standalone + embedded), react-usestream.

## Optional

- [Roadmap](https://skein.js.org/roadmap.md): Milestones, shipped features, known gaps vs LangGraph, and non-goals.
- [llms-full.txt](https://skein.js.org/llms-full.txt): The user-facing docs concatenated into one file for wholesale ingestion.