# Fastro: a FastAPI boilerplate with auth, jobs and caching wired from the start

> Fastro is a vertical-slice FastAPI starter that combines SQLAlchemy 2.0, Pydantic v2, sessions, CSRF, OAuth, background jobs and rate limiting into one uv workspace. It is a single-service foundation, not a microservices scaffold.

**benavlabs/FastAPI-boilerplate** — An extendable async API using FastAPI, Pydantic V2, SQLAlchemy 2.0, PostgreSQL and Redis.

- Repository: https://github.com/benavlabs/FastAPI-boilerplate
- Website: https://benavlabs.github.io/FastAPI-boilerplate/
- Stars: 2,093 · Forks: 313
- Language: Python
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/benavlabs-fastapi-boilerplate

## Fastro targets single-service Python APIs, not microservice meshes

Fastro is a starting point for building a production FastAPI backend as a single service. The project is explicit about where it does not fit: if you need a monorepo microservices scaffold, the docs site points to alternatives rather than trying to stretch the design. That stated boundary runs through every architectural decision, from the shared database session to the single Docker Compose configuration and the way Alembic handles migrations.

Vertical-slice means each feature area, auth, CRUD, caching, jobs, sits in its own slice of the codebase rather than being distributed across layers. The bp CLI is plugin-ready in the sense that third parties can distribute a plugin package that mounts new commands or feature integrations into bp without modifying the main project.

Python 3.11 or newer is required, as declared in the workspace pyproject.toml. The repository is MIT-licensed and is not archived. Three releases have shipped since May 2026: v0.17.0 on 2026-05-08, v0.18.0 on 2026-05-24 and v0.19.0 on 2026-06-24, with the last push to the repository on 2026-10-06.

## The uv workspace separates the deployable backend from the bp CLI

The repository is a uv workspace with two members: backend, which is the deployable application, and cli, which is the bp developer tool. The pyproject.toml at the workspace root declares this structure but is itself not a deployable package. One virtual environment at the root covers both members, so a single sync step installs everything and the two packages share the same dependency resolution.

The top-level directory holds pyproject.toml, uv.lock, README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE.md, a backend/ directory, a cli/ directory, a docs/ directory, a .github/ directory, and configuration files including .pre-commit-config.yaml, .dockerignore and zensical.toml. Separating backend/ from cli/ means application changes do not require touching CLI code, and CLI updates do not require touching application code.

The uv.lock file at the root tracks the pinned dependency state for the whole workspace. If a dependency in backend/ and a dependency in cli/ conflict, uv workspace resolution handles it, though the README does not document any known conflicts of that kind. The lock file is the place to check if a dependency upgrade causes unexpected behavior.

## Running uv sync and the first bp command

The pyproject.toml documents the core workflow commands in its comments. Syncing the whole workspace requires one step:

```bash
uv sync
```

After that, the bp CLI is available through the workspace runner:

```bash
uv run bp ...
```

To run the backend test suite:

```bash
uv run pytest
```

To install bp as a system tool available outside the repository directory:

```bash
uv tool install --editable ./cli
```

The README directs readers to the docs site at benavlabs.github.io/FastAPI-boilerplate for the full user guide, which covers the CLI subcommands in detail. Docker Compose files for local, production and nginx-fronted deployments are generated by bp rather than written by hand, which means the CLI is a required setup step before standing up any containers. The bp tool also audits environment variables and mounts third-party plugins, so how you invoke it depends on which of those tasks you are doing first.

## Sessions, CSRF, OAuth and API keys arrive before you write the first route

Auth is the feature most API starters leave as an exercise. Fastro wires four mechanisms into the starting point: server-side sessions and CSRF protection through crudauth, a PyPI package rather than an embedded module; OAuth with Google configured by default; and API key support for machine-to-machine callers. Annotated type aliases cover all FastAPI dependency injection points, keeping the boilerplate inside route functions minimal once the auth layer is in place.

Using crudauth as a PyPI dependency means auth updates come through a package version bump rather than a fork. The tradeoff is that you are bound to what that package exposes. What happens when you need a custom claims model or a non-Google OAuth provider is not covered in the README, and those cases fall to the docs site.

JWT is not in the open source tier. The comparison table shows auth in Fastro as sessions, OAuth and API keys, and adds JWT only in the FastroAI column. If your API consumers expect JWT rather than session cookies or API keys, the free project does not cover that case without moving to the paid template. That is a meaningful constraint for any team building against a JWT-expecting frontend or mobile client.

## The @cache decorator accepts Redis or Memcached; Taskiq jobs take Redis or RabbitMQ

Caching works through a decorator and a provider API. The @cache decorator is the calling interface, and the provider underneath is either Redis or Memcached. That separation means switching cache backends requires changing the provider configuration rather than the application code that calls @cache. TTL defaults and eviction policies at the decorator level are not described in the README.

Background jobs use Taskiq, and the broker is either Redis or RabbitMQ. Redis can serve both caching and job brokering simultaneously if you choose it for both roles, which reduces the number of services you run locally. Docker Compose covers Redis in the generated setup. RabbitMQ is not mentioned in the Docker Compose description, so adding it means extending the generated compose file yourself.

Rate limiting is configured with per-tier and per-path rules. That combination lets a free-tier user receive a different limit per endpoint than a paid-tier user, which is a common pattern for tiered API products. How tiers are defined and what values they accept are not described in the README. The docs site is where the full rate-limit configuration lives.

## SQLAdmin is env-toggled; Alembic migrations carry a prod-confirm gate

The admin panel is SQLAdmin-based, optional and controlled by an environment variable. Setting that variable to the right value enables the panel; leaving it out keeps the panel out of the deployment. That design reduces the chance of an admin interface appearing in a service that did not intend to expose one, but it also means the variable must be present in any environment where the panel is needed.

Alembic handles database migrations and ships with a prod-confirm gate: a prompt that fires before applying migrations to a production database. Most boilerplates omit this check entirely. Before your first automated deploy, confirm how the gate behaves, because a CI pipeline running migrations unattended will block on that interactive prompt unless the pipeline handles it explicitly.

Postgres runs in the bundled Docker container by default, but the README also covers Neon, a serverless Postgres offering, with a dedicated guide on the docs site. FastCRUD provides CRUD generics and pagination on top of SQLAlchemy 2.0 async sessions. Pydantic v2 models handle validation across both the API and the ORM layer.

## Payments, email, frontend and observability are FastroAI features, not Fastro ones

Fastro does not include Stripe billing, subscription or credits handling, feature entitlements tied to plan tiers, transactional email, a frontend, Logfire observability, or PydanticAI agent integration. All of those belong to FastroAI, a commercial template built on the same backend foundation. The README describes the two as: Fastro is the free open-source foundation, and FastroAI is the paid template for shipping a complete SaaS.

The comparison table contains one detail that is easy to miss: the bp CLI appears only in the Fastro column, not in FastroAI. Moving to the paid template means the scaffolding and env audit tooling does not come with it.

Community support runs through Discord, with the invite link discord.com/invite/TEmPs22gqB listed in the README. CONTRIBUTING.md at the repository root is the documented entry point for contributors, and CODE_OF_CONDUCT.md and LICENSE.md are also at the root. The licence is MIT, and LICENSE.md holds the full text. This article does not offer legal advice on what that licence allows or restricts.

## Conclusion

Fastro is worth the setup if you are building a new Python API backend and want sessions, OAuth, FastCRUD, caching, background jobs and rate limiting in place from day one. Skip it if you need JWT in the open source tier, a microservices scaffold, or Stripe billing and transactional email out of the box: those belong to FastroAI, the paid template built on this same foundation. Before starting, read the Alembic migration docs for the prod-confirm gate, because an automated CI pipeline running migrations against a production database will need to handle that interactive prompt explicitly.

## FAQ

### What is Fastro (FastAPI-boilerplate)?

Fastro is an open source FastAPI boilerplate that includes SQLAlchemy 2.0, Pydantic v2, server-side sessions, OAuth, FastCRUD, Taskiq background jobs, Redis or Memcached caching, and a bp CLI for scaffolding. It requires Python 3.11 or newer and is MIT-licensed.

### How do I set up benavlabs FastAPI-boilerplate?

Run uv sync from the repository root to install both the backend and CLI packages into a shared venv. After that, uv run bp runs the CLI and uv run pytest runs the test suite. The docs site at benavlabs.github.io/FastAPI-boilerplate covers the full setup guide.

### What is the difference between Fastro and FastroAI?

Fastro is the free MIT-licensed backend with auth, CRUD, caching, jobs and rate limiting. FastroAI is a paid commercial template that adds Stripe billing, feature entitlements, transactional email, a frontend, Logfire observability and PydanticAI agents on top of the same backend.

### Does Fastro support serverless Postgres?

Yes. The README covers Neon, a serverless Postgres offering, as an alternative to the bundled Docker container, with a dedicated guide on the docs site at benavlabs.github.io/FastAPI-boilerplate.

### What message broker does Taskiq use in Fastro?

Fastro supports Redis or RabbitMQ as the Taskiq broker. Redis is included in the generated Docker Compose setup; RabbitMQ requires extending the compose file.

## Sources

- [benavlabs/FastAPI-boilerplate on GitHub](https://github.com/benavlabs/FastAPI-boilerplate)
- [License: MIT](https://github.com/benavlabs/FastAPI-boilerplate/blob/main/LICENSE)
- [Project website](https://benavlabs.github.io/FastAPI-boilerplate/)
- [README](https://github.com/benavlabs/FastAPI-boilerplate/blob/main/README.md)
- [Releases](https://github.com/benavlabs/FastAPI-boilerplate/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/benavlabs-fastapi-boilerplate