Getting started

Avo turns your Rails app into something your whole team can operate. You describe your data in small Ruby configuration files, and Avo builds the interface around it: the screens to browse and edit records, the actions that run your business logic, the dashboards, the search. It's the layer your team logs into every day to run the product, whether you use it as an admin panel, an internal tool, or the app itself.

Everything in these docs fits into three rings:

1. The core. Describe your data once and Avo generates the full interface around it.
2. Add-ons. Optional gems that extend the core with new capabilities as your needs grow.
3. Your code. Escape hatches at every level, so configuration never boxes you in.

The core

You don't build screens with Avo. You tell it what data you have, and it builds the screens.

A resource maps to one of your models and declares its fields: first_name as text, birthday as date, cover_photo as file, and so on. From that, Avo renders the views to list, show, create, and edit records, complete with associations, validations surfaced from your models, and file uploads through Active Storage.

# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
  def fields
    field :id, as: :id
    field :first_name, as: :text
    field :birthday, as: :date
    field :cover_photo, as: :file
    field :projects, as: :has_many
  end
end

Around resources sit the tools your team works with every day: actions to run business logic on one or many records, filters to slice lists, and search to get to any record fast.

Add-ons

The core covers managing records. Add-ons extend it toward whatever job your app or your internal tools have to do. Each one is a separate gem you install when the need shows up, and it slots into the same configuration style as everything else.

Find and organize records

• Global Search: search every resource from one box.
• Dynamic Filters: let users stack their own filter combinations without you writing each one.
• Resource Scopes: reuse the model scopes you already trust as one-click segments.
• Searchable Associations: type-to-search when attaching related records, even in huge tables.
• Record Reordering: drag-and-drop ordering for lists where position matters.
• Menu Editor: shape the sidebar into a navigation that makes sense for your team.

Capture and edit data

• Forms: standalone forms and pages beyond your resources, for surveys, settings, and bespoke flows.
• Nested Records: create and edit associated records inside the parent form.
• Reactive Fields: fields that show, hide, or update based on what the user picks.
• Media Library: manage every uploaded asset in one place.

Run day-to-day operations

• Dashboards and cards: metrics and charts at a glance.
• Kanban: drag-and-drop boards for pipelines and workflows.
• Notifications: in-app notifications for the events that matter.
• Collaboration: comments and status updates on records, so context stays with the data.
• Audit Logging: who did what, and when.

Control who can do what

• Authorization: granular permissions using Pundit policies.
• Custom Controls: decide exactly which buttons and actions each user sees.

Connect other systems

• JSON API: expose your resources as a JSON API for integrations and mobile apps.
• HTTP Resource: manage data from an external API as if it were local.

Your code

When configuration isn't enough, you drop down to plain Rails. Avo is built to be extended, not worked around:

• Custom fields slot into panels and views just like built-in ones.
• Resource tools embed your own partials inside a resource's pages.
• Custom tools give you entire pages built from partials or View Components.
• Eject views copies any of Avo's own templates into your app for full control.
• JavaScript & Stimulus is baked in for sprinkling interactivity anywhere.
• Plugins package your extensions for reuse across apps.

Security

Avo runs entirely inside your Rails app. It ships as a gem, reads and writes through your own models, and your data stays on your servers; there's no external dashboard or third-party service between your team and your database.

On top of that, you control access at every level: authentication plugs into whatever you already use (Devise, the Rails 8 scaffold, or anything that gives you a current user), authorization enforces granular permissions through Pundit policies, Custom Controls decide which buttons each user even sees, and Audit Logging keeps a record of who did what.

Build it with AI agents

The same thing that makes Avo fast for you makes it fast for AI agents: features are small, declarative Ruby files, so agents like Claude Code or Cursor generate resources, actions, and filters that work on the first try instead of hallucinating view code.

We lean into it. Point your agent at the docs map so it pulls accurate, current docs, and install the official Avo skills, pre-built workflows for building resources, writing tests, creating field types, and more. The Agentic engineering page walks through the full setup for every editor.

Seamless upgrades

Avo ships as a gem, so none of its internals live in your app. Upgrading is bundle update avo: no file conflicts, no generated code drifting out of date.

Start here

1. Install Avo in your app
2. Hook up the current user
3. Create your first resource
4. Set up authorization
5. Explore the live demo app

Where to go next

• Best practices for structuring a real-world Avo app.
• Guides with worked examples and recipes.
• FAQ for common setup questions.
• Avo 3 to Avo 4 upgrade if you're coming from an existing app.
• Technical support when you get stuck.