# skein-js

> The open-source LangGraph Platform alternative, for TypeScript (LangGraph Platform is now LangSmith Deployment): a self-hosted Agent Protocol server for LangGraph.js, plus a drop-in replacement for the LangGraph CLI (`skein dev` ⇄ `langgraph dev`). Serve any LangGraph.js graph as a standard HTTP + SSE agent server — threads, runs, streaming, interrupts, long-term memory — from Express, Fastify, NestJS, or Next.js. Runs on your own infrastructure and your own Postgres, deployable anywhere you can run a container (Cloud Run, Railway, Fly.io, Render, AWS, Kubernetes, or your own VPS), with no license key and no per-run bill. Open source (Apache-2.0). Includes cron/scheduled runs. Not yet implemented: an `/mcp` endpoint.

skein-js implements LangChain's Agent Protocol, so the whole LangChain client ecosystem (`@langchain/langgraph-sdk`, the `useStream` React hook, Agent Chat UI, LangGraph Studio) works against your server by changing only a URL — no custom SDK, no bespoke wire format. It deliberately reuses LangGraph OSS (runtime, checkpointers, config parser, schemas, SDK types) and rebuilds only the durable-production, multi-framework, drop-in-CLI layer OSS lacks. The one thing to know when consuming it: every framework adapter takes the same `{ config } | { deps }` options bag — point it at a `langgraph.json`, or hand it a `ProtocolDeps` you assembled (in-memory for dev, Postgres + Redis for production).

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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/getting-started.md): Guided walkthrough from zero to a running server, then to production (all three on-ramps).
- [Scaffolding a project](https://github.com/skein-js/skein-js/blob/main/docs/scaffolding.md): `npm create skein-js@latest` — what it generates, every flag, monorepo use, and how to write the same files by hand.
- [Using skein-js](https://github.com/skein-js/skein-js/blob/main/docs/using-skein.md): Terse consumer/agent cheat-sheet — install, the `{ config } | { deps }` seam, mount on each framework, call it.
- [Building blocks](https://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/recipes/index.md): Task snippets — coupled WhatsApp replies, decoupled email-to-WhatsApp routing, human-in-the-loop, memory, authentication providers, webhooks, and deploy.
- [Overview & architecture](https://github.com/skein-js/skein-js/blob/main/docs/index.md): The problem skein solves, what the Agent Protocol is, and how skein is built.
- [README](https://github.com/skein-js/skein-js/blob/main/README.md): The project landing page — principles, quick start, package tour.

## Guides

- [LangGraph CLI compatibility](https://github.com/skein-js/skein-js/blob/main/docs/langgraph-cli-compat.md): Every `langgraph.json` field + the `skein` command mapping (`dev`/`up`/`build`/`dockerfile`).
- [Framework adapters](https://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/embedding.md): The in-code on-ramp — serve a compiled graph with no `langgraph.json` and no CLI.
- [Serving a graph as a plain endpoint](https://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/agent-protocol.md): The REST + SSE endpoint inventory skein implements, plus the auth route→permission map.
- [Features](https://github.com/skein-js/skein-js/blob/main/docs/features.md): "Can skein do X?" — every capability in one page, grouped by what you're trying to build, each linking out.
- [Runs](https://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/channels.md): Connect authenticated provider sources and durable destinations through a LangGraph workflow.
- [Streaming](https://github.com/skein-js/skein-js/blob/main/docs/streaming.md): LangGraph stream modes mapped onto Agent Protocol SSE, with cross-instance fan-out.
- [Errors & logging](https://github.com/skein-js/skein-js/blob/main/docs/errors-and-logging.md): What happens when a graph throws — the `RunError` payload, `exposeErrorStacks`, the `Logger` interface, and the `skein dev` failure block.
- [React SDK / useStream](https://github.com/skein-js/skein-js/blob/main/docs/react-sdk.md): Frontend compatibility — `@langchain/langgraph-sdk` and `useStream` over SSE.
- [Storage](https://github.com/skein-js/skein-js/blob/main/docs/storage.md): `SkeinStore`, in-memory vs Postgres, pgvector semantic search, checkpointer, and `getStore()` in a graph.
- [Runs & Redis](https://github.com/skein-js/skein-js/blob/main/docs/runs-and-redis.md): The run engine, the queue, and cross-instance streaming with Redis.
- [Observability](https://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/deploy-railway.md), [Fly.io](https://github.com/skein-js/skein-js/blob/main/docs/deploy-fly.md), [Render](https://github.com/skein-js/skein-js/blob/main/docs/deploy-render.md), [AWS App Runner and ECS Fargate](https://github.com/skein-js/skein-js/blob/main/docs/deploy-aws.md), [Kubernetes](https://github.com/skein-js/skein-js/blob/main/docs/deploy-kubernetes.md), [a plain VPS](https://github.com/skein-js/skein-js/blob/main/docs/deploy-vps.md), and [what does and doesn't work on Vercel/serverless](https://github.com/skein-js/skein-js/blob/main/docs/deploy-serverless.md).
- [Bundling skein](https://github.com/skein-js/skein-js/blob/main/docs/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://github.com/skein-js/skein-js/blob/main/docs/console.md): A web UI for a running server — assistants, threads, live run tails, interrupt approve/resume, time travel, the store browser, and crons. Served by the server itself at `/console`; on by default under `skein dev`, opt-in via `http.console` elsewhere.
- [Building a custom adapter](https://github.com/skein-js/skein-js/blob/main/docs/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/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`. Run once, never installed.

## Examples

- [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

- [Reuse-first architecture](https://github.com/skein-js/skein-js/blob/main/docs/reuse.md): What skein reuses from LangGraph OSS vs rebuilds.
- [Roadmap](https://github.com/skein-js/skein-js/blob/main/docs/roadmap.md): Milestones, shipped features, known gaps vs LangGraph, and non-goals.
- [AGENTS.md](https://github.com/skein-js/skein-js/blob/main/AGENTS.md): For agents/humans working ON skein itself (contributor guide), not consuming it.
- [llms-full.txt](https://github.com/skein-js/skein-js/blob/main/llms-full.txt): The user-facing docs concatenated into one file for wholesale ingestion.