Autumn 🍂
Spring Boot-style web framework for Rust, built on Axum.
Autumn assembles proven Rust crates into a convention-over-configuration web
stack with proc-macro ergonomics, framework defaults, and customization options when
you need them. If Spring Boot, Rails, or Laravel feels familiar, Autumn aims
for that same "ship the app, not the plumbing" shape in Rust.
Features
- Route and app macros -
#[get], #[post], #[put], #[delete], routes![], #[autumn_web::main]
- Pre-rendering pages to static HTML -
#[static_get] + static_routes![] with autumn build pre-rendering to dist/
- Application builder -
.routes(), .tasks(), .static_routes(), .scoped(), .merge(), and .nest()
- Configuration and profiles - defaults,
autumn.toml, autumn-{profile}.toml, and AUTUMN_* overrides
- Database ergonomics - async Postgres primary/replica pools,
Db extractor for the primary/write role, #[model], #[repository], hooks, and embedded migrations
- HTML stack - Maud templating, bundled htmx, Tailwind build pipeline, and static asset serving
- Operations -
/health, /actuator/*, structured logging, metrics, and graceful shutdown
- Background work -
#[scheduled] tasks, #[job] handlers, one-off #[task] scripts via autumn task, and runtime task visibility at /actuator/tasks
- Companion workflows - Autumn Harvest is the separate durable workflow engine for multi-step orchestration when
#[scheduled] or #[job] is not enough
- Transactional email - optional
mail feature with Maud templates, log/file/SMTP transports, and a Mailer extractor
- Security primitives - session cookies, auth extractor, security headers, CSRF, and
#[secured]
- File storage (optional) - pluggable
BlobStore trait with built-in Local and S3-compatible backends, HMAC-signed URLs, and MultipartField::save_to_blob_store (see storage guide)
- CLI workflow -
autumn new, autumn setup, autumn dev, autumn build, autumn migrate, autumn console, and autumn task
Quickstart
# Install the published CLI
cargo install autumn-cli --version 0.9.0 --locked
# Local development only, from an Autumn checkout:
# cargo install --path autumn-cli
# Create a new project
autumn new my-app
cd my-app
# Optional: download Tailwind CSS for styled builds
autumn setup
# Optional: scaffold a CRUD resource (see docs/guide/generators.md)
# autumn generate scaffold Post title:String body:Text published:bool
# Development server with file watching
autumn dev
# Or run without watch mode
# cargo run
Need to poke at your data? autumn console scaffolds and runs a pre-wired
playground binary — same config, same database URL resolution, same pool as the
app (see the data playground guide):
autumn console
autumn console --repl # interactive Rhai prompt, no compile per query
Visit http://localhost:3000. Autumn also auto-mounts /health,
/actuator/health, /actuator/info, and /static/js/htmx.min.js.
Install a prebuilt binary (macOS & Linux)
Get the autumn CLI without compiling from source — no Rust toolchain required:
curl -fsSL https://raw.githubusercontent.com/autumn-foundation/autumn/trunk-dev/scripts/install.sh | sh
The installer detects your OS and architecture (macOS or Linux, x86_64 or aarch64), downloads the matching prebuilt binary, verifies its sha256 checksum, and installs it to ~/.local/bin/autumn — printing the line to add if that directory isn't on your PATH. Override the target dir with AUTUMN_INSTALL_DIR, or pin a version with AUTUMN_VERSION=vX.Y.Z (or --version vX.Y.Z).
Prefer a manual download? Grab the tarball plus its .sha256:
- Latest:
https://github.com/autumn-foundation/autumn/releases/latest/download/autumn-<target>.tar.gz
- Pinned:
https://github.com/autumn-foundation/autumn/releases/download/<tag>/autumn-<target>.tar.gz
where <target> is one of x86_64-unknown-linux-musl, aarch64-unknown-linux-musl, x86_64-apple-darwin, or aarch64-apple-darwin (Linux binaries are static musl — no glibc version dependency). Binaries track tagged crate releases (e.g. v0.9.0); latest is the most recent released version — there are no rolling trunk-dev builds.
Install a prebuilt binary (Windows)
Windows ships a native x86_64-pc-windows-msvc build as a .zip (not a tarball). The POSIX install.sh above does not run on Windows; use the PowerShell installer instead:
irm https://raw.githubusercontent.com/autumn-foundation/autumn/trunk-dev/scripts/install.ps1 | iex
It downloads autumn-x86_64-pc-windows-msvc.zip, verifies its sha256 (Get-FileHash), extracts autumn.exe to %LOCALAPPDATA%\autumn\bin, and prints the line to add if that directory isn't on your PATH. Override the install dir with -Dir, or pin a version with -Version vX.Y.Z.
Prefer a manual download? Grab the zip plus its .sha256:
- Latest:
https://github.com/autumn-foundation/autumn/releases/latest/download/autumn-x86_64-pc-windows-msvc.zip
- Pinned:
https://github.com/autumn-foundation/autumn/releases/download/<tag>/autumn-x86_64-pc-windows-msvc.zip
Verify with Get-FileHash autumn-x86_64-pc-windows-msvc.zip -Algorithm SHA256 and compare against the .sha256 file, then extract autumn.exe and put it on your PATH.
Prefer building from source? cargo install --path autumn-cli still works.
Watching custom directories
autumn dev always watches src/, static/, templates/, and migrations/
plus the project's top-level config files (autumn.toml, Cargo.toml,
Cargo.lock, build.rs, tailwind.config.js). To watch additional folders
(for example, custom view or locale trees), add a [dev] section to
autumn.toml:
[dev]
watch_dirs = ["views", "locales"]
Listed directories are watched recursively in addition to the defaults.
Multi-segment paths like content/locales are supported. Changes inside
them trigger a server restart and a full browser reload. Paths under
target/ and dotted directories are still ignored.
Entries must be project-relative; absolute paths, .. traversal,
target, and dotted directories (e.g. .git) are rejected with a
warning. Missing directories are skipped at startup.
If you add #[static_get] routes, autumn build pre-renders them into
dist/.
Local-Safe vs Production-Safe
Autumn still distinguishes between "works on your laptop" and "safe to run in a
multi-replica deployment":
- Local-safe defaults: in-memory sessions, pretty logs in
dev, scheduler.backend = "in_process" for #[scheduled], single-binary startup, and no inbound request deadline (so a debugger pause never 503s you).
- Production-safe options:
/live, /ready, /startup probes, OTLP telemetry config, Redis-backed sessions, Redis-backed channels/jobs, Postgres-coordinated scheduled tasks, an experimental zero-dependency embedded 2-node cluster (authenticated gossip membership plus an eventually consistent cluster-wide counter — an additional option for a shared counter without standing up Redis, not a production-safe substitute for the backends above and not a leader-election or mutual-exclusion primitive), container scaffolding from autumn new, explicit migration jobs before web replicas roll, and a built-in inbound request timeout (the prod profile smart-defaults server.timeouts.request_timeout_ms = 30000) so a single hung handler returns a clean 503 and frees its worker instead of starving the pool — no hand-written tower layers. Streaming responses (SSE) are never interrupted — the deadline bounds the response head, not the body stream — and WebSocket upgrades are bounded only for the handshake, never the live socket. Any route can override with #[get("/export", timeout_ms = 120000)] or timeout = "off".
Deploys can also carry a proven capacity contract: autumn calibrate measures
what a build sustains and records capacity.lock, autumn calibrate --check
gates rebuilds against it in CI, and [server] capacity_contract lets the binary
admission-control against its own proven envelope instead of a hand-tuned guess
(see Capacity Contracts).
If you are deploying beyond a single process, read the
Cloud-Native Guide before treating the defaults as
done.
Database Topologies
Autumn supports three explicit database shapes:
- Single primary: set
database.url or database.primary_url. Writes,
transactions, advisory locks, and autumn migrate use that primary role.
- Primary plus read replica: set
database.primary_url and
database.replica_url, with optional primary_pool_size,
replica_pool_size, and replica_fallback = "fail_readiness" or
"primary".
- One-shot migrator path: run
autumn migrate once against the primary
before rolling web replicas. Production web replicas should keep
auto_migrate_in_production = false.
database.url and DATABASE_URL remain valid for existing single-URL apps.
For new production config, prefer AUTUMN_DATABASE__PRIMARY_URL so the write
role is named plainly. autumn doctor --strict reports missing primaries,
unsafe production startup migrations, role connectivity failures, and stale
replica migrations without printing credentials.
Autumn Harvest
Autumn Harvest is the companion workflow engine for durable, multi-step work:
workflow history, activity retries, timers, singleton orchestration, and
long-running business processes. It is intentionally a separate release train
from autumn-web: Harvest can depend on Autumn Web's AppState and builder
surface, but Autumn Web's examples and tests should not need Harvest in order to
ship a web release. That keeps the dependency graph pointed in one direction
instead of forming a circular release dependency.
Use built-in #[scheduled] tasks and #[job] handlers for lightweight app-local
background work. Reach for Harvest when the work needs workflow durability or a
dedicated runner. See the Harvest pointer page
and the Autumn Harvest repository
for the engine itself, and ADR-0016
for why durable workflows stay out of Autumn core.
Example
This is the small-app shape Autumn is built around:
use autumn_web::prelude::*;
#[get("/")]
async fn index() -> &'static str {
"Welcome to Autumn!"
}
#[get("/hello/{name}")]
async fn hello_name(name: autumn_web::extract::Path<String>) -> String {
format!("Hello, {}!", *name)
}
#[autumn_web::main]
async fn main() {
autumn_web::app()
.routes(routes![index, hello_name])
.run()
.await;
}
Built On
Examples
See EXAMPLES.md for the full catalog with personas, journeys, prerequisites, run commands, and success proofs.
| Example | Description |
|---|
examples/hello | Minimal hello-world app with route macros and no database |
examples/flock | WASM island spike: a server-rendered maud page whose home route mounts a Yew CSR "literary boids" widget compiled to wasm32-unknown-unknown, with a custom 'wasm-unsafe-eval' CSP |
examples/todo-app | Full-stack CRUD app with Diesel, Maud, htmx, Tailwind, JSON API, bearer-token auth, and MCP tool projection |
examples/blog | Blog engine with admin UI, validation, and pre-rendering pages to static HTML via #[static_get] |
examples/cms | WordPress-parity CMS: posts/pages, taxonomies, media, moderated comments, revisions, roles, themes, plugin hooks |
examples/bookmarks | Repository macro, generated CRUD API, profiles, scheduled tasks, actuator endpoints, and app metrics (a domain counter + timer on /actuator/prometheus) |
examples/bookmarks-distributed | Primary/replica Postgres, multi-replica web tier behind nginx, advisory-lock scheduling, a two-node self-clustering substrate needing no coordination service, and Docker Compose deployment |
|
Documentation
- Guide index — every guide page, grouped by task — the
full table of contents for
docs/guide/; the list below is a selection of
highlights, not the whole guide
- What's new in 0.9.0 — a walkthrough of the release: load shedding, retry budgets and deadlines on by default, adaptive admission control, a transactional outbox and fenced leases, SQLite fleets with one database per tenant, and MCP Tasks
- What's new in 0.8.0 — a walkthrough of the release: simulated networks and build-time query budgets, SQLite as a full backend,
Money and ledgered data, mTLS and DNS-01 certificates, shadow deploys, and capability-sandboxed plugins
- What's new in 0.7.0 — a walkthrough of the release: host-preparing deploys and fleets, deterministic simulation testing, the new model attributes, failure-capsule replay, and a request path that allocates ~59% less
- Getting Started Guide
- Authentication — sessions, password policy, login/logout,
#[secured], lockout, and remember-me; the hub that links OAuth, step-up, and MFA
- Dev-Loop Latency Budget — p50/p95/max budgets per change class, measurement methodology, and CI gates for
autumn dev
- Cache Coherence —
autumn cache audit: the build fails when a #[repository] write can leave a #[cached] read stale with no invalidation covering it, turning cache invalidation from a runtime footgun into a compile-time obligation
Stability
Autumn commits to Semantic Versioning for its public
API starting at 1.0.0. See STABILITY.md for the full
definition of the stable surface, the MSRV policy, and the migration-guide
process for future major releases.
Until 1.0.0, Autumn is in its 0.x series — see the
pre-1.0 notes for what that means in practice.
Requirements
- Rust 1.88.0+ (edition 2024)
- PostgreSQL for database-backed apps
Autumn can still run without a database if you omit the [database] section.
Platform support
Develop on macOS, Linux, or Windows; deploy on Linux.
On Windows the core journey — autumn new, doctor, setup, dev, test,
foreground serve, and managed Postgres — is Tier 1: works natively, and a
windows-latest CI job walks that whole journey on every pull request. The
Unix-native slices — the autumn serve --daemon lifecycle, the autumn deploy
actions that reach a host over SSH, and the bash contributor gate scripts — are
Tier 2: supported via WSL2, and fail
fast on native Windows with an error naming the policy rather than
half-working.
See Platform support for the full
command-by-command policy, the Windows prerequisites autumn doctor flags, and
how to run the Tier 2 commands under WSL2.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
