Rust off Rails: The Opinionated Web Stack for the AI Era

Rust off Rails is a revolutionary approach to web development: a framework that ships zero lines of actual code. Instead, it provides a comprehensive set of Markdown specifications that instruct AI coding agents on exactly how to construct a full-stack Rust application. It enforces a "blessed" stack, a standardized layout, and a singular, definitive way to implement every feature.

🚀 Quick Start

To get the system running, you can use the following methods:

• Shell: curl -fsSL https://rustoffrails.org/install.sh | sh
• Claude Code: /plugin marketplace add rust-off-rails/rustoffrails

[!IMPORTANT] Before piping scripts to your shell, always review the INSTALL.md documentation.

Example: A live Kanban board created by an AI in just 7 prompts.

---

🛠️ The Agent Experience: A Case Study

Imagine initializing a project called bookshelf for tracking and reviewing books with a future-proof API.

/offrails:new bookshelf: people track and review books, with an API for a mobile app later

The AI's internal process:

1. Analysis: Reads AGENTS.md $\rightarrow$ conducts interview $\rightarrow$ defines doctrine $\rightarrow$ sets structure.
2. Interview:
   • Auth method? $\rightarrow$ a) magic link (Recommended) $\checkmark$
   • API style? $\rightarrow$ b) REST + OpenAPI $\checkmark$
3. Planning:
   • Stack: Inertia + Svelte | Postgres (Prod) / SQLite (Local).
   • Schema: User $\leftarrow$ Book (title, author, rating 1–5) $\leftarrow$ Review (body, stars 1–5).
   • Endpoints: /api/v1/books, /api/v1/reviews using bearer tokens.
4. Execution:
   • $\checkmark$ migration/src/m20261013_120000_create_books.rs
   • $\checkmark$ src/models/book.rs
   • $\checkmark$ src/controllers/books.rs
   • $\checkmark$ web/src/pages/Books/Index.svelte (+ 71 other files)
5. Verification:
   • cargo clippy --all-targets -- -D warnings $\rightarrow$ Pass
   • pnpm --dir web typecheck $\rightarrow$ Pass
   • cargo nextest run (SQLite) $\rightarrow$ 142 Passed
   • cargo nextest run (Postgres 18) $\rightarrow$ 142 Passed

Definition of Done: Everything is green. Run bin/setup then bin/dev.

---

🧠 The Philosophy: Decisions as Code

Rust off Rails is a framework composed of decisions, not libraries. It eliminates the "hallucination" or improvisation phase of AI coding by providing the judgment already written down.

The Founding Rule

All code is written by AI. Every single line of Rust, SQL, HTML, CSS, TypeScript, and every Dockerfile is generated by an agent.

Humans are relegated to providing intent:

• Writing specifications in product/
• Answering interview questions
• Providing conversational feedback

By making boilerplate "free" and enforcing conventions via the agent, the product specifications remain the ultimate source of truth.

Markdown as the Framework

Instead of shipping a binary library, Off Rails ships a precise specification.

• Owned Code: Components like session management, job queues, and Inertia adapters are rendered directly into your codebase.
• Agent-Centric Opinions: Crate selection, naming conventions, and error handling are decided once and for all.
• Batteries Included: Guides and recipes exist for auth, caching, email, uploads, and real-time features.

---

🔄 The Development Lifecycle

1. Interview: AI asks product-focused questions with recommended defaults.
2. Plan: A concise blueprint (resources, pages, jobs) is saved to product/ with clear acceptance criteria.
3. Generate: The agent follows "Generator Recipes": $\text{Migration} \rightarrow \text{Model} \rightarrow \text{Failing Tests} \rightarrow \text{Controller} \rightarrow \text{Views}$.
4. Green: The code must pass fmt, clippy, and tests on both SQLite and Postgres.

The Agent's Toolkit

---

🛠️ Technical Specifications

The Stack

• Backend: Axum $\cdot$ Tokio $\cdot$ SeaORM
• Database: SQLite (Local) / Postgres (Production)
• Templating/CSS: Askama $\cdot$ Tailwind
• Utilities: lettre (Email) $\cdot$ tracing (Logging)
• Deployment: Single binary, single Docker image.

Frontend Modes (FRONTEND_MODE)

• htmx (Default): Askama templates (compile-time checked) + htmx.
• inertia: Server-side routing with React or Svelte pages.
• spa: A decoupled JSON API and a standalone single-page app.
• api (In Progress): Pure backend with versioned APIs for external partners.

UI Library Options: react (default) or svelte. API Options: none, rest (OpenAPI + tokens), graphql, or both.

Built-in Observability

The system includes a development dashboard featuring:

• Traces & Hot Functions
• Mailbox & Jobs Dashboard
• Live Presence

Performance Note: The dashboard overhead is approximately $\approx 1\mu s$ per request in release builds.

---

⚖️ The Paradigm Shift

The Heritage: Rust off Rails takes the best elements of two beloved frameworks—specifically the "Convention over Configuration" and "Generators" of Ruby on Rails—and reshapes them for the Rust ecosystem and AI agents.