Agent SDK overview

How Forest agents fit into your stack across supported languages.

A Forest agent is the lightweight backend that connects Forest to your data. It runs in your infrastructure, executes your business logic, and exposes your data and workflows to two consumers:

• The Forest UI, what your operations team uses daily.
• AI agents (Claude, Dust, Decagon, internal builds), via the built-in MCP server, with the same permissions and audit trail.

The agent is the substrate that makes Forest the operational layer for regulated work, not a thin wrapper around your database.

Supported languages

Node.js

@forestadmin/agent, TypeScript-first, multi-datasource, plugin ecosystem. The most actively developed agent.

Features: full TypeScript support with type inference, multi-datasource, plugin ecosystem, advanced customization API, Cloud and self-hosted deployment.

Ruby

forest_admin_agent, ActiveRecord and Mongoid support, Rails integration.

Features: ActiveRecord and Mongoid datasources, Rails integration, custom actions and fields, approval workflows.

Architecture

All Forest agents follow the same architecture:

Your databases & APIs
       ↓
Forest Agent (your backend)
       ↓
Forest API
       ↓
   ┌────┴────┐
Forest UI   MCP server
                ↓
            AI agents

The agent is the only component with direct access to your data. Everything else, the UI, the API gateway, AI agents, talks to the agent over HTTPS.

Core concepts

Concept	What it is
Datasources	Connections to your databases, APIs, or custom sources. Multiple per agent.
Collections	Each table or model becomes a collection, what operators browse, search, and act on.
Customizations	Actions, computed fields, segments, relationships, hooks, plugins. Defined in code.
Hooks	Intercept and modify CRUD operations to enforce business rules.
MCP server	Exposes your collections, actions, and workflows to AI agents under the same permissions and audit trail.
Authentication	Forest handles SSO, SAML, 2FA, SCIM provisioning, and role-based permissions.

Choosing an agent

Agent	Best for	Deployment
Node.js (@forestadmin/agent)	Modern apps, TypeScript projects, multi-datasource setups	Cloud or self-hosted
Ruby (forest_admin_agent)	Rails applications	Self-hosted

If you’re starting fresh, the Node.js agent gets the most feature work. The Ruby agent is at parity for the core feature set and is the right choice for Rails-native teams.

Migrating from a v1 agent?

If you’re using a legacy agent (forest-express-sequelize, forest-express-mongoose, forest-rails, or django-forestadmin v1), the migration path is documented:

Migration guide

Step-by-step migration from v1 to the current generation.

Legacy reference

Reference for v1 agents, maintained for migration purposes only.

Getting started

1. Choose your agent

   Node.js or Ruby, pick the one that matches your stack.

2. Install the package

   Add @forestadmin/agent (npm) or forest_admin_agent (gem) to your project.

3. Configure datasources

   Connect your databases, APIs, or custom sources.

4. Add customizations

   Build actions, computed fields, and segments in code.

5. Deploy

   Run the agent in your infrastructure (self-hosted) or have Forest host it (Cloud).

Next steps

Node.js reference

Complete API reference for @forestadmin/agent.

Ruby reference

Complete API reference for forest_admin_agent.

Quickstart

Get an agent running in 10 minutes.

Need help?

Documentation

Full docs portal.

Community

Ask the community.

Support

Reach the Forest team.