# Get started with Rust off Rails

> From zero to a running app: one install line, one line describing your app, a short interview. The agent writes every line of code and stops only when the tests are green. Framework version 0.7.3. HTML version: https://rustoffrails.org/start

## 1. Install

One line, on macOS or Linux:

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

- **Rust**, if `cargo` is missing: it asks first, then runs the official rustup installer. It never uses sudo.
- **The cargo tools** the framework uses: `sea-orm-cli`, `cargo-nextest`, `cargo-watch`, only the missing ones.
- **The framework**, from the GitHub release, SHA-256 verified, in `~/.offrails/`, plus the `offrails` command.
- **The Claude Code plugin**, if `claude` is on your PATH. For other agents, it prints the one-line prompt.
- **Docker, Node and pnpm** are only detected, never installed. No telemetry.

Read before you pipe: [the install script](https://rustoffrails.org/install.sh) and [INSTALL.md](https://github.com/rust-off-rails/rustoffrails/blob/main/INSTALL.md). Or print the plan without changing anything:

```sh
curl -fsSL https://rustoffrails.org/install.sh | sh -s -- --dry-run
```

### Already in Claude Code?

Install just the plugin, once per machine:

```claude
/plugin marketplace add rust-off-rails/rustoffrails
/plugin install offrails@offrails
```

That adds nine skills, from `/offrails:new` to `/offrails:upgrade`, and the guardrail hooks. Both do nothing outside a Rust off Rails app.

## 2. What you need

The installer takes care of the first two. By hand:

- **Rust, stable** (required), with rustup:

  ```sh
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```

- **Three cargo tools** (required): migrations, the test runner, rebuild-on-save.

  ```sh
  cargo install --locked sea-orm-cli cargo-nextest cargo-watch
  ```

- **Docker** (optional): Postgres for tests, `docker compose`, deploys. Without it everything runs on SQLite, and CI runs the Postgres tests.
- **Node 24 LTS and pnpm** (only for a JS UI: the `inertia` or `spa` modes, or htmx with islands):

  ```sh
  corepack enable pnpm
  ```

- **A coding agent**: Claude Code (recommended), or Codex, Cursor, or any agent that reads `AGENTS.md`.

## 3. Your first app

Start Claude Code in an empty directory:

```sh
mkdir bookshelf && cd bookshelf
claude
```

Then describe the app in one line:

```claude
/offrails:new bookshelf: people track books they've read
```

Or from any terminal, with the `offrails` command the installer added (it starts Claude Code, or Codex, or prints the prompt for your agent):

```sh
offrails new bookshelf "people track the books they've read"
```

1. **The interview.** Product questions only, at most three rounds, each with a recommended default listed first. Answer with a letter, in your own words, or with "you decide" to take the defaults. For example: Accounts? a) Magic link (Recommended) b) Email + password c) Invite-only d) None. Who owns data? a) Each user owns their records (Recommended) b) Teams c) Shared. Frontend? a) htmx (Recommended) b) inertia c) spa d) api.
2. **The plan.** Resources, pages, jobs and everything it assumed. Nothing is generated until you say yes.
3. **Generation.** Your answers go into `product/` specs and the app's `AGENTS.md`, then migrations, models, controllers, templates, tests, a Dockerfile, `compose.yaml` and CI, one vertical slice at a time.
4. **Green on both databases.** It isn't done until the Definition of Done passes: fmt, clippy, and the whole test suite on SQLite and Postgres.

### Run it

```sh
bin/setup && bin/dev
```

`bin/setup` creates `.env`, builds the CSS, compiles, and migrates and seeds the development database. `bin/dev` prints the URL to open: https://localhost:3000 (HTTP/2) when [mkcert](https://github.com/FiloSottile/mkcert) is installed, otherwise http://localhost:3000 with a note saying why (framework 0.6.1+; never a self-signed certificate, because browsers drop login cookies on it). It rebuilds, migrates and reloads open tabs whenever the agent changes something.

### What you get on day one

- `/dev`: dev tools (mailbox and jobs tiles, routes, system info, pending migrations, test buttons).
- `/dev/mailbox`: every email the app sends in development, rendered, plus mailer previews.
- `/admin/jobs`: the jobs dashboard (in production too, behind admin access).
- Docker: `docker compose up --build` runs the production image against Postgres.
- CI: `.github/workflows/ci.yml` runs the tests on SQLite and Postgres and builds the Docker image.
- `/up`: the health check (503 while migrations are pending).

## 4. Your first feature

Say it:

```claude
/offrails:feature let people review books; email the owner
```

Or write it in `product/features/reviews.md`, in plain English, then:

```claude
/offrails:feature
```

With no argument it builds whatever changed in `product/`. It asks only what changes the build, writes the spec first, then migration → model → failing tests → code, and ticks each acceptance criterion once its test passes on both databases.

## 5. Ship it

```claude
/offrails:deploy kamal
```

Targets: Kamal (your own server), Fly.io, Render or Railway. It writes the Dockerfile and the target's config, runs the Definition of Done, builds the image and checks `/up` locally, then stops and confirms before anything outward-facing: the exact commands, what each costs or changes, and which secrets you supply.

## 6. Upgrading your app

Each app keeps its own pinned copy of the framework in `.offrails/`, so nothing changes until you upgrade. Commit first. Then get the latest release:

```sh
offrails update
```

See whether your app is behind (it compares content, not just version numbers; framework 0.4.0+):

```sh
cd my-app && offrails upgrade --check
```

And upgrade (framework 0.4.0+):

```sh
offrails upgrade
```

It starts your agent with the upgrade recipe: Claude Code runs `/offrails:upgrade`, opencode and Codex get the recipe automatically, and for any other agent it prints a prompt to paste. The agent shows you a plan before changing anything.

On a release before 0.4.0, run `offrails update`, then ask your agent, in the app:

```prompt
Upgrade this Rust off Rails app to the framework in ~/.offrails/current, following https://github.com/rust-off-rails/rustoffrails/blob/main/generators/upgrade.md step by step. Reconcile, don't re-create; never edit applied migrations. Start from a clean git tree, show me the plan before changing anything, and finish with the Definition of Done on SQLite and Postgres.
```

Several releases behind? Upgrade one release at a time. Details: [the guide](https://rustoffrails.org/guide.md).

## Without Claude Code

Any agent that reads `AGENTS.md` works: Codex, Cursor, and others. Clone the framework repository, then tell your agent:

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

Generated apps carry `AGENTS.md` and a pinned copy of the framework in `.offrails/`, so later sessions need no setup.

Only want your agent to read the docs, with nothing installed? Connect it to the hosted MCP server: [https://rustoffrails.org/mcp](https://rustoffrails.org/mcp) (Claude Code, Claude, Cursor, ChatGPT, Codex).

## Troubleshooting

- **Is my machine set up right?** Run `offrails doctor`:

  ```sh
  offrails doctor
  ```

- **The first build is taking forever.** Expected: about 10 minutes cold. Rebuilds take seconds.
- **The agent says the Postgres tests were skipped.**

  ```sh
  docker compose up -d db
  TEST_DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres cargo nextest run
  ```

- **Where are the logs?** The terminal running `bin/dev` (set `RUST_LOG` in `.env`). Failed jobs: `/admin/jobs`, or:

  ```sh
  cargo run -- jobs list --state discarded
  ```

  Emails: `/dev/mailbox`. Environment, database and migrations: `/dev/system`.
- **A page says migrations are pending.** Press its Run migrations button, or:

  ```sh
  cargo run -- db migrate
  ```

- **Port 3000 is already taken.**

  ```sh
  PORT=3001 bin/dev
  ```

- **Something's red.**

  ```claude
  /offrails:check
  ```

  After hand edits, `/offrails:doctor` audits and `/offrails:doctor --fix` repairs.

Next: [the guide](https://rustoffrails.org/guide.md), the day-to-day model. Ideas to try: [the prompt gallery](https://rustoffrails.org/prompts).