Migrating from Agent v1 to v2 - Forest Documentation

This guide covers migrating from any v1 agent (forest-express-sequelize, forest-express-mongoose, forest-rails, django-forestadmin v1) to the current generation. The migration unlocks workflows, the MCP server for AI agents, multi-datasource, decision traces, and everything Forest has shipped since the original admin-panel era. Most teams complete the migration in 1-2 days with zero downtime.

What v2 changes

The new generation is a rebuilt agent with a cleaner, more composable customization API. The biggest changes you’ll see during migration:

Multi-datasource is native. A single agent can connect to multiple databases and APIs.
Customization happens via a fluent API on collections. agent.customizeCollection('users', users => users.addField(...)).
Computed fields declare their dependencies explicitly. dependencies: ['firstName', 'lastName'].
Relationships are first-class. Many-to-one, one-to-many, many-to-many, and external relations replace most legacy “smart relationships”.
Routes are no longer overridden directly. Most v1 route overrides become hooks or computed fields.

Before you start

Inventory your customizations

List every Smart Action, Smart Field, Smart Relationship, Smart Segment, and route override in your current project. Each step page below covers one of these surfaces.

Set up a test environment

Create a Remote test environment in Forest (Project Settings → Environments → Add). The new agent will run there before you flip production.

Back up your project

Export your current Forest project layout. While the layout is preserved across the agent swap, having a baseline is good practice.

Plan parallel running

Both agents can run side by side during migration.

Migration steps

Install the new agent

Install the new packages alongside your existing ones. The legacy agent keeps running on its current port; the new one runs on a different port.

Node.js
Ruby

npm install @forestadmin/agent
npm install @forestadmin/datasource-sql
# or @forestadmin/datasource-mongo, @forestadmin/datasource-mongoose, etc.

# Gemfile
gem 'forest_admin_agent'
gem 'forest_admin_rails'
gem 'forest_admin_datasource_toolkit'
gem 'forest_admin_datasource_customizer'
gem 'forest_admin_datasource_active_record'

Migrate datasources

Re-declare your data sources using the new datasource API. See Datasources.

Migrate Smart Actions

Convert each Smart Action to the new addAction API. See Smart Actions.

Migrate Smart Fields

Convert computed fields to addField with explicit dependencies. See Smart Fields.

Migrate Smart Relationships

Convert legacy smart relationships to native relations or external relations. See Smart Relationships.

Migrate Smart Segments

Update segments to use condition trees instead of ORM-specific queries. See Smart Segments.

Test side by side

Run both agents simultaneously. Point a test environment at the new agent and verify behavior matches v1, especially actions, computed fields, and segments.

Switch your environment URL

Once you’re confident, update your Forest environment URL to point at the new agent. The UI configuration is preserved.

Remove legacy packages

Once production has been stable on the new agent for a few days, remove the legacy packages and clean up the old code.

What’s preserved

Your Forest UI configuration is not affected by the agent migration:

Layouts, segments, dashboards, charts
Roles, permissions, scopes, teams
Workspaces, workflows, inboxes
Approval workflow configurations
Smart Action visibility settings

These all live in Forest’s UI configuration and continue to work as long as the new agent exposes the same collection and field names.

What needs updating

Surface	Where it changes	Step page
Datasource configuration	Code	Datasources
Smart Actions	Code	Smart Actions
Smart Fields	Code	Smart Fields
Smart Relationships	Code	Smart Relationships
Smart Segments	Code	Smart Segments
Route overrides	Reimplemented as hooks	See Hooks
Environment variables	`FOREST_ENV_SECRET` and `FOREST_AUTH_SECRET` are reused	No change
Database	No change	No change

Common issues

Field names changed between v1 and v2

The new agent treats field names as case-sensitive and prefers camelCase by convention. If your legacy code used snake_case, you can either rename the fields or use the rename option on the datasource to keep the original names exposed.

A Smart Action's form behaves differently

The Smart Action form API is more structured in v2. Fields are declared explicitly. See Smart Actions for the new form syntax.

A computed field is slow

The new agent supports batched computed fields: getValues receives an array of records. If you naively port a v1 get function inside a .map(async ...), you’ll keep the same N+1 problem. Aggregate the underlying query.

A relationship doesn't appear in the UI

The new relationship API requires you to declare both sides. If you only declared one direction, the UI may not surface it. See Smart Relationships.

Get help

Step pages

Per-feature migration instructions with side-by-side examples.

Community

Migration questions and patterns from other teams.

Support

Direct help from the Forest team.

​What v2 changes

​Before you start

​Migration steps

​What’s preserved

​What needs updating

​Common issues

​Get help