# Rat Stack: reference for building an app and its cloud as one typed program

> Source: <https://ratstack.sh/>
> Published: 2026-09-23 16:49:26+00:00

# 🐀 Rat Stack

The 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.

Vendor it like a library. Keep the bins you need and pull the rest.

## Connect an agent

Paste this into your coding agent:

```
Read https://ratstack.sh/llms.txt and use rat-stack as the reference
for how we build: Effect for the hard parts, Alchemy for the
infrastructure, and a fence that makes the easy path the right
one. Search its rules and skills before you write code, follow
its patterns, and tell me when my code breaks them.
```

Or connect the [MCP](https://modelcontextprotocol.io) server directly:

```
# Claude Code
claude mcp add --transport http rat-stack https://ratstack.sh/mcp

# Codex
codex mcp add rat-stack --url https://ratstack.sh/mcp
```

Cursor reads `~/.cursor/mcp.json`:

```
{ "mcpServers": { "rat-stack": { "url": "https://ratstack.sh/mcp" } } }
```

Install the skills into any agent that reads a skills folder:

```
npx skills add joelhooks/rat-stack
```

Every 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.

## Four ideas

- **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.
- **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.
- **Floor.** Raise the worst case. Small cuts to failure rates multiply how long an agent can run unattended.
- **Range.** Think wider. Building got fast and deploying did not. Layers that carry their own infrastructure close that gap. If it compiles, it deploys.

The [vision](https://ratstack.sh/VISION.md) has the sources and the reasoning.

## The shelf

Every piece is a bin you can push in or pull out.

What to notice: removing a bin means deleting its package and the one line that provides it. Everything else still passes the checks.

## One capability, every surface

What to notice: the four boxes share one handler and one set of schemas. Add a capability once and every surface picks it up.

## The pattern in code

This is the whole search capability. Every surface below calls it.

``` js
export const search = defineCapability("search", {
  annotations: {
    idempotent: true,
    readOnly: true,
  },
  description:
    "Search rat-stack repository law and skills. Returns stable resource ids for read.",
  failure: Schema.Never,
  handler: ({ limit, query }) => {
    const matches = searchContent(query, limit);

    return Effect.succeed({
      matches,
      total: matches.length,
    });
  },
  input: Schema.Struct({
    limit: Schema.optional(Schema.Finite),
    query: Schema.String,
  }),
  output: SearchOutput,
});
```

What to notice: the schemas and handler live together, so the command line, HTTP, MCP, and sandbox projections cannot quietly disagree.

## Learn the stack

Skills are short guides your agent can install (see above). You can also just read them here.

### See how the pieces fit

- [learn-alchemy](https://ratstack.sh/skills/learn-alchemy) — Learn how Alchemy 2 turns an Effect program into a planned Cloudflare deployment.
- [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.

### Learn by building

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

### Choose what you keep

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

These 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.

## Source files

- [AGENTS.md](https://ratstack.sh/AGENTS.md) — What you may change, which commands to run, and which changes need approval.
- [VISION.md](https://ratstack.sh/VISION.md) — What this starter is for and what a useful copy should keep.
- [README.md](https://ratstack.sh/README.md) — What is in the repo, how the example works, and how to run it.
- [vendor/README.md](https://ratstack.sh/vendor/README.md) — How to pin an unpublished package and when to remove the local copy.
- [pins.md](https://ratstack.sh/pins.md) — Exact dependency values declared by every workspace package.
- [log.md](https://ratstack.sh/log.md) — What changed in the files served here, newest first.
- [Effect 4 examples](https://ratstack.sh/resources/effect-4-reference-projects.svx) — Working examples for the exact Effect version used by this repo.
- [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.