{"slug": "rat-stack-reference-for-building-an-app-and-its-cloud-as-one-typed-program", "title": "Rat Stack: reference for building an app and its cloud as one typed program", "summary": "Rat Stack launched as a reference stack for building an app and its cloud as one typed program, combining Effect for application logic and Alchemy for infrastructure inference, and is distributed as an MCP server at https://ratstack.sh/mcp plus installable agent skills via `npx skills add joelhooks/rat-stack`. The stack defines four ideas — Pieces, Trust, Floor, and Range — and serves MCP clients on protocol 2026-07-28 without sessions while older clients get a session held by a Durable Object. One capability handler and its schemas project to the command line, HTTP, MCP, and sandbox surfaces so they cannot disagree.", "body_md": "# 🐀 Rat Stack\n\nThe reference for building an app and its cloud as one typed program. [Effect](https://effect.website) owns the hard parts. [Alchemy](https://alchemy.run) infers the infrastructure from the code. The fence raises the floor, so agents can build it and you can still trust it.\n\nVendor it like a library. Keep the bins you need and pull the rest.\n\n## Connect an agent\n\nPaste this into your coding agent:\n\n```\nRead https://ratstack.sh/llms.txt and use rat-stack as the reference\nfor how we build: Effect for the hard parts, Alchemy for the\ninfrastructure, and a fence that makes the easy path the right\none. Search its rules and skills before you write code, follow\nits patterns, and tell me when my code breaks them.\n```\n\nOr connect the [MCP](https://modelcontextprotocol.io) server directly:\n\n```\n# Claude Code\nclaude mcp add --transport http rat-stack https://ratstack.sh/mcp\n\n# Codex\ncodex mcp add rat-stack --url https://ratstack.sh/mcp\n```\n\nCursor reads `~/.cursor/mcp.json`:\n\n```\n{ \"mcpServers\": { \"rat-stack\": { \"url\": \"https://ratstack.sh/mcp\" } } }\n```\n\nInstall the skills into any agent that reads a skills folder:\n\n```\nnpx skills add joelhooks/rat-stack\n```\n\nEvery MCP client works. Clients on protocol 2026-07-28 are served without sessions; older clients get a session of their own, held by a Durable Object.\n\n## Four ideas\n\n- **Pieces.** An Alchemy Layer carries its own infrastructure. A service tag is the product’s API. A Layer is one vendor’s implementation. Swapping vendors is a one-line change.\n- **Trust.** Make the easy path the right path. The codebase and the compiler stop mistakes that rules and style guides can only ask about. Remove a binding and the code that uses it stops compiling.\n- **Floor.** Raise the worst case. Small cuts to failure rates multiply how long an agent can run unattended.\n- **Range.** Think wider. Building got fast and deploying did not. Layers that carry their own infrastructure close that gap. If it compiles, it deploys.\n\nThe [vision](https://ratstack.sh/VISION.md) has the sources and the reasoning.\n\n## The shelf\n\nEvery piece is a bin you can push in or pull out.\n\nWhat to notice: removing a bin means deleting its package and the one line that provides it. Everything else still passes the checks.\n\n## One capability, every surface\n\nWhat to notice: the four boxes share one handler and one set of schemas. Add a capability once and every surface picks it up.\n\n## The pattern in code\n\nThis is the whole search capability. Every surface below calls it.\n\n``` js\nexport const search = defineCapability(\"search\", {\n  annotations: {\n    idempotent: true,\n    readOnly: true,\n  },\n  description:\n    \"Search rat-stack repository law and skills. Returns stable resource ids for read.\",\n  failure: Schema.Never,\n  handler: ({ limit, query }) => {\n    const matches = searchContent(query, limit);\n\n    return Effect.succeed({\n      matches,\n      total: matches.length,\n    });\n  },\n  input: Schema.Struct({\n    limit: Schema.optional(Schema.Finite),\n    query: Schema.String,\n  }),\n  output: SearchOutput,\n});\n```\n\nWhat to notice: the schemas and handler live together, so the command line, HTTP, MCP, and sandbox projections cannot quietly disagree.\n\n## Learn the stack\n\nSkills are short guides your agent can install (see above). You can also just read them here.\n\n### See how the pieces fit\n\n- [learn-alchemy](https://ratstack.sh/skills/learn-alchemy) — Learn how Alchemy 2 turns an Effect program into a planned Cloudflare deployment.\n- [learn-rat-stack](https://ratstack.sh/skills/learn-rat-stack) — See how Effect,[XState](https://stately.ai/docs/xstate) ,[TypeScript](https://www.typescriptlang.org) , Alchemy, and four agent interfaces fit together.\n\n### Learn by building\n\n- [add-a-capability](https://ratstack.sh/skills/add-a-capability) — Learn how one Effect action becomes a command, HTTP route, MCP tool, and sandbox call.\n- [add-a-lifecycle-machine](https://ratstack.sh/skills/add-a-lifecycle-machine) — Learn how XState owns a lifecycle while Effect owns its work, errors, and services.\n\n### Choose what you keep\n\n- [keep-or-cut](https://ratstack.sh/skills/keep-or-cut) — Learn which pieces depend on each other, then keep only the ones your project needs.\n\nThese pieces are pre-release (Effect 4 rc, XState 6 alpha, [TypeScript 7](https://github.com/microsoft/typescript-go), Alchemy beta). APIs move; `pins.md` has the exact versions this repo builds against.\n\n## Source files\n\n- [AGENTS.md](https://ratstack.sh/AGENTS.md) — What you may change, which commands to run, and which changes need approval.\n- [VISION.md](https://ratstack.sh/VISION.md) — What this starter is for and what a useful copy should keep.\n- [README.md](https://ratstack.sh/README.md) — What is in the repo, how the example works, and how to run it.\n- [vendor/README.md](https://ratstack.sh/vendor/README.md) — How to pin an unpublished package and when to remove the local copy.\n- [pins.md](https://ratstack.sh/pins.md) — Exact dependency values declared by every workspace package.\n- [log.md](https://ratstack.sh/log.md) — What changed in the files served here, newest first.\n- [Effect 4 examples](https://ratstack.sh/resources/effect-4-reference-projects.svx) — Working examples for the exact Effect version used by this repo.\n- [One action, four interfaces](https://ratstack.sh/resources/schema-projections-and-code-mode.svx) — Why one typed action powers the command line, HTTP, MCP, and sandbox.", "url": "https://wpnews.pro/news/rat-stack-reference-for-building-an-app-and-its-cloud-as-one-typed-program", "canonical_source": "https://ratstack.sh/", "published_at": "2026-09-23 16:49:26+00:00", "updated_at": "2026-09-23 17:00:38.360910+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools", "ai-infrastructure"], "entities": ["Rat Stack", "Effect", "Alchemy", "Cloudflare", "XState", "TypeScript", "Model Context Protocol", "joelhooks"], "alternates": {"html": "https://wpnews.pro/news/rat-stack-reference-for-building-an-app-and-its-cloud-as-one-typed-program", "markdown": "https://wpnews.pro/news/rat-stack-reference-for-building-an-app-and-its-cloud-as-one-typed-program.md", "text": "https://wpnews.pro/news/rat-stack-reference-for-building-an-app-and-its-cloud-as-one-typed-program.txt", "jsonld": "https://wpnews.pro/news/rat-stack-reference-for-building-an-app-and-its-cloud-as-one-typed-program.jsonld"}}