Getting started

With Avo, your Rails app is your company's command center. You describe your data in small Ruby files, and your team gets what they need to run the business from it: screens to browse and edit records, actions that run your business logic, dashboards, search, and an AI assistant they can ask in plain words. Support asks the app and gets an answer instead of waiting on a developer, ops fixes the order themselves, and you get back to the product.

The AI follows the same rules as everything else in Avo. Your team asks from the chat bar in the Avo app, or from Claude, ChatGPT or Cursor over MCP, and it sees only what that person's policies allow. In the chat, updates and deletes wait until someone clicks Confirm, and with Audit Logging every change leaves a trail. AI in your Avo app walks through both.

Use it as an admin panel, an internal tool, or the app itself; it runs inside your Rails app either way.

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.

Building with an AI coding agent?

Your agent can read these docs too. Agentic engineering shows how to point Claude Code, Cursor and the rest at the docs map and the skills that ship inside the gem, so what they write matches the Avo version you run.

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.

Let your team ask the app

• AI chat: a chat bar on every Avo page that answers from your data and waits for Confirm before it updates or deletes anything.
• MCP Server: your team asks from Claude, ChatGPT or Cursor, as themselves, with their own permissions.
• AI in your Avo app: how the two compare, and the rules they share.

Connect other systems

• 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: no file conflicts, no generated code drifting out of date.

bin/rails avo:update

That resolves every Avo gem you have — core plus any add-ons — and updates them together, conservatively. It can commit and push the updated lockfile too.

Since avo >= v4.3.11

The status page (/status under your Avo mount path) marks each gem that has a newer release. In development, its Update all button runs the same task, shows the output and offers to restart the app. What's new is a changelog of Avo and the gems you run, newest first, with what you have installed marked.

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.