Rust off Rails

The opinionated web stack for the AI era.

Rust off Rails is a web framework for AI coding agents. It ships no library you depend on: it's a set of Markdown files that tell agents how to build a full-stack Rust web app (one blessed stack, one directory layout, one way to do each thing), plus the app template those files describe, as real, tested files the agent copies instead of retyping (template/).

The convention lives in the prose; the code is copied from the template and its parts, then written by the agent for everything app-specific. Humans still write none of it.

Take only what you need

Nothing here is all-or-nothing. There is no framework code hidden under your app: what we give you is copied into it, so it's all in your repo and yours to change. (Apps still use ordinary crates like Axum and SeaORM.) Your agent gets good ideas and inspiration: the crates we'd recommend and why, and tested reference code for things we like, such as job processing, presence and authenticated webhooks, in the samples repo, with screenshots. Use the whole template, one part, or only a convention. We're still experimenting and building real apps with it, and so far it has gone better than we expected.

Standing on giants

We take the best ideas of two great ecosystems and bring them together in one stack.

• From Ruby on Rails:
  • convention over configuration;
  • generators (new, scaffold), Active Record-style models and migrations;
  • Rails 8 authentication;
  • the Solid trifecta: jobs, cache and pub/sub in the database, no Redis;
  • Turbo 8-style page-refresh broadcasts;
  • mailer previews, bin/rails tasks, and Kamal-ready Docker with /up.
• From Elixir and Phoenix:
  • Oban persistent jobs and the Oban Web dashboard;
  • Swoosh's local mailbox;
  • phx.gen.auth magic links and the "check your mailbox" hint;
  • LiveDashboard-style dev tools;
  • Channels, Presence and PubSub;
  • multi-node clustering and "let it crash" supervision;
  • Ecto's explicit data layer (no callbacks);
  • the pending-migrations page.
• And also: htmx, Inertia.js, Tailwind, shadcn-style owned components, and end-to-end types from Rust to TypeScript.

RAILS_MAP.md maps every Rails concept to its Off Rails equivalent, plus a Borrowed from Phoenix / Elixir section.

The deal

Rules of the framework

1. All code is written by AI. No exceptions. Humans write intent: specs in Markdown, interview answers and feedback. Agents write every line of Rust, SQL, HTML, CSS, TypeScript, config and scripts. If a human edits code anyway, the agent treats the edit as a spec change, records it, and owns that code from then on.
2. Strong opinions, aimed at agents. Every decision an agent would otherwise improvise (crate choice, file location, naming, error handling, testing) is already made in these docs.
3. Everything Rails has, mapped. Active Record, Action Controller, Action View, Active Job, Action Mailer, Action Cable, Active Storage, Solid Cache/Queue/Cable, generators, bin/rails, credentials, Kamal. See RAILS_MAP.md.

Using it

Install (one line)

curl -fsSL https://rustoffrails.org/install.sh | sh

It checks for Rust (and offers rustup), installs the cargo tools the framework uses as prebuilt binaries, downloads and SHA-256-verifies the framework into ~/.offrails/, installs the Claude Code plugin if claude is on your PATH, and adds an offrails command. No sudo, no telemetry, and it's safe to re-run. Add --dry-run to see the plan first. INSTALL.md explains every step, with a manual equivalent.

offrails new bookshelf "people track the books they've read"   # starts Claude Code (or Codex) with /offrails:new
offrails doctor                                                # prerequisites and versions
offrails update                                                # latest release

Or by hand: Claude Code plugin

/plugin marketplace add rust-off-rails/rustoffrails      # or a local checkout: /plugin marketplace add /path/to/rustoffrails
/plugin install offrails@offrails

Then, in an empty directory:

/offrails:new bookshelf: people track the books they've read and review them

The agent interviews you first (accounts? who owns data? htmx or React? where will it run?), using recommended defaults so you can just say "you decide". It confirms a plan, then builds. The skills also trigger on plain requests ("make me a new Rust web app…").

The plugin also installs hooks. They only act inside Off Rails apps (directories with .offrails/):

• Edit guard: blocks edits to .offrails/ (read-only) and web/src/types/ (generated by ts-rs).
• Convention check: after each edit, flags raw SQL outside the kernel, banned crates or packages, and /:id routes.
• Stop gate: the agent can't end a turn while cargo fmt --check or cargo check fails.
• Session start: orients the agent and notices when the app's framework version is behind the plugin's.

Each app still vendors the docs into .offrails/, pinned to a version, so the app keeps working with any agent, with or without the plugin.

With Codex, Cursor, or any agent that reads AGENTS.md

Read /path/to/rustoffrails/AGENTS.md and make me a new app called "bookshelf".

Generated apps carry AGENTS.md and .offrails/, so later sessions need no setup.

Then

Describe features in plain language, or write them as specs in product/:

Scaffold Book with title:string, author:string, published_on:date, rating:integer.
Users must be logged in to create books. Send the owner an email when a book gets a review.

The template and its parts

A new app is a copy of template/app/: a complete, compiling app (htmx) with the kernel, security headers, CSRF, sessions, Host allowlist, rate limiting, log redaction, SQLite and Postgres, /dev tools, Tailwind, CI, Docker and the kernel tests, renamed and green in minutes instead of an hour of generated Markdown. On top of it go the parts the product needs: the mailer and dev mailbox, jobs and their dashboard, accounts (password, magic link, TOTP), realtime with presence, and a LiveDashboard-style dev dashboard. They're the tested samples from rust-off-rails/samples (screenshots of every screen there). Your agent proposes the ones your app needs, you confirm, and later needs are one command: cargo offrails add-part <name>. Once copied, the app owns the code (guides/samples.md).

The generators (offrails-gen: new, add-part, list-parts, generate, destroy, snippets) are a small standard-library Rust tool, so they work the same on Linux, macOS and Windows. Features start from a snippet (small tested code to copy: a feed, slugs, Markdown, a pager, a theme toggle; template/snippets) or a generator (cargo offrails g resource posts title:string), both optional, both the app's once written: small files per feature, one marked line per shared spot. Pages are built from a component kit (Askama macros, light and dark, branded from one brand.toml) in five layouts, and cargo offrails prove screenshots and checks every page and writes docs/proof/PROOF.md, tying each acceptance criterion to its passing tests and pages.

Field tests: real apps, ported by agents

We test the framework by having agents port well-loved open-source apps to it. Each port puts the docs, the template and the parts up against a product with years of real-world design behind it, and every rough edge an agent hits goes back into the framework.

• fizzyer: a Rust port of Fizzy, 37signals' kanban-style tracker. Repository coming soon.
• **A Fr