Forest Runtime

Forest’s orchestrator coordinates your workflows but never executes the steps itself — that runs on Forest Runtime, deployed on your own infrastructure. Forest Runtime polls the orchestrator for pending steps, runs them locally, and reports only the results back. Setting it up is a one-time addition, not a migration: you deploy Forest Runtime and either point your agent at it or embed it in the agent — your collections and existing workflows are untouched. Because it talks to your data through your own Forest agent, the Forest orchestrator never sees your records — data read and written by data steps stays within your infrastructure.

One exception: AI steps and MCP Tasks send prompt content, which can include record data, to an LLM provider and remote tools — so workflows aren’t fully air-gapped. See AI provider.

Do I need Forest Runtime?

Yes — Forest Runtime is what executes your workflow steps. Automatically-triggered workflows especially: a webhook call or an AI assistant can fire at any time, with no guarantee anyone has Forest open in a browser, so those runs can only execute server-side. Until Forest Runtime is installed, both automated triggers stay locked in the workflow’s settings. Running on infrastructure you control also keeps the records handled by data steps out of Forest’s infrastructure — decisive for compliance or data-residency requirements, or when a step needs access to systems reachable only from within your network.

How it works

A workflow is triggered — by a user, a webhook, or an AI assistant. The Forest orchestrator queues the pending steps.
Forest Runtime polls the orchestrator and pulls the steps assigned to it.
Each step runs locally, reaching your data and actions through your Forest agent.
It reports the step outcome back to the orchestrator, which advances the workflow.

Prerequisites

A recent Forest Admin agent — the minimum version depends on how you run Forest Runtime (below).
A PostgreSQL database for production: Forest Runtime persists its run state there. A database-free mode exists for testing only.

Running Forest Runtime

Run Forest Runtime one of two ways:

Embedded in your Node.js agent — one line in your agent, nothing separate to deploy. The simplest option.
Standalone — a separate process (Docker or CLI), to scale it independently of your agent or to use it with a Ruby agent.

Embedded in the Node.js agent

Requirements:

@forestadmin/agent — embedded mode arrived in 1.84.0, but the options shown below (schema, ai, encryptionKey, the tuning knobs) landed in later releases, so use a recent version.
Node.js ≥ 22.12.0 — required by the executor package.
The executor package, installed at the exact version your agent pins. It’s an optional peer dependency the agent loads dynamically at runtime, so tsc won’t flag it when it’s missing — but agent.start() throws “The embedded workflow executor requires the @forestadmin/workflow-executor package”. The pin is exact (a ^ range conflicts), so install that specific version — find it in your lockfile or with npm info @forestadmin/agent@<your-agent-version> peerDependencies (pin the version you actually run — without it, npm answers for latest, whose pin may differ):
npm install @forestadmin/workflow-executor@<pinned-version>
TypeScript 5.5+ — the package ships zod 4, which is only tested against TypeScript 5.5 and later. On TypeScript 4.x its typings can’t even be parsed, and skipLibCheck won’t help (it suppresses type errors, not the syntax errors these typings trigger).

Then add one line — the executor runs inside the agent process, so there’s nothing else to deploy:

createAgent(options)
  .addDataSource(/* ... */)
  .addWorkflowExecutor({ database: { uri: process.env.DATABASE_URL } })
  .start();

Safe to reuse the database your agent already reads: the executor keeps its tables in a dedicated forest Postgres schema, so they stay out of the public schema your datasource introspects and never show up as collections in your panel. Pass a schema if you’d rather name it differently.Creating that schema needs the CREATE privilege on the database. If your role doesn’t have it, have an administrator create the schema and grant the role access to it — the executor checks whether the schema already exists before trying to create one, so a pre-created schema boots fine with schema-level privileges only.

It inherits your agent’s secrets and Forest connection, so you only configure:

Option	Description
`database`	Postgres connection — a URI or Sequelize options. Persists run state. Its tables live in the `forest` schema unless you pass a different `schema` here. Required unless `inMemory`.
`inMemory`	`true` runs without a database (testing only — runs are lost on restart).
`agentUrl`	How the executor reaches your agent. Auto-derived when the agent runs on its own server; required when the agent is mounted on Express, Fastify or NestJS.
`port`	Loopback port the executor listens on internally (default `3400`).
`ai`	Bring your own LLM instead of Forest’s AI server: `{ provider: 'anthropic' \| 'openai', model, apiKey }` (all three required together). Omit to keep using Forest’s server.
`encryptionKey`	At-rest key (AES-256-GCM) for OAuth-protected MCP connector credentials. Generate with `openssl rand -hex 32`. Omit if you don’t use them.
`pollingIntervalS`, `stepTimeoutS`, `aiInvokeTimeoutS`, `stopTimeoutS`, `maxChainDepth`, `schemaCacheTtlS`	The same tuning knobs as standalone, in camelCase — same defaults. Log verbosity follows your agent’s own logger, so there’s no separate log-level option here.

Embedded has full configuration parity with standalone: your own AI provider (ai), the encryption key, and every tuning knob are all settable here. It only inherits your agent’s secrets and Forest connection; set nothing and AI steps use Forest’s AI server.

Standalone (Docker or CLI)

Run Forest Runtime as its own service — the way to run it with any agent other than the v2 Node.js one (which can also embed it), and to scale or deploy it separately. 1. Point your agent at it with the workflow executor URL, so the agent mounts the route that forwards workflow requests to Forest Runtime (relaying the JWT). It’s supported across both agent generations:

Agent	Config	Min version
`@forestadmin/agent` — Node.js (v2)	`createAgent({ workflowExecutorUrl })`	1.79.0
`forest-express` — Node.js (v1, incl. `-sequelize` / `-mongoose`)	`Liana.init({ workflowExecutorUrl })`	10.7.0
`forest_admin_rails` — Ruby (v2)	`config.workflow_executor_url`	1.31.0
`forest-rails` — Ruby (v1)	`ForestLiana.workflow_executor_url`	9.18.0

createAgent({
  // ...
  workflowExecutorUrl: process.env.WORKFLOW_EXECUTOR_URL, // e.g. http://localhost:3400
})

Liana.init({
  // ...
  workflowExecutorUrl: process.env.WORKFLOW_EXECUTOR_URL,
})

# config/initializers/forest_admin_rails.rb
ForestAdminRails.configure do |config|
  # ...
  config.workflow_executor_url = ENV['WORKFLOW_EXECUTOR_URL']
end

# config/initializers/forest_liana.rb
ForestLiana.workflow_executor_url = ENV['WORKFLOW_EXECUTOR_URL']

The Python agents (agent-python, django-forestadmin) don’t support the workflow executor yet.

If the workflow executor URL is left unset, the agent returns 404 on those routes and Forest Runtime never receives any work. When the agent and Forest Runtime run on separate hosts, use an internal address the agent can reach on Forest Runtime’s HTTP port (default 3400). 2. Run the executor as a Docker image or via the CLI:

docker run -d \
  --add-host=host.docker.internal:host-gateway \
  -e FOREST_ENV_SECRET="your-env-secret" \
  -e FOREST_AUTH_SECRET="your-auth-secret" \
  -e AGENT_URL="http://host.docker.internal:3351" \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/mydb" \
  -p 3400:3400 \
  ghcr.io/forestadmin/workflow-executor:latest

FOREST_ENV_SECRET="your-env-secret" \
FOREST_AUTH_SECRET="your-auth-secret" \
AGENT_URL="https://your-agent-url" \
DATABASE_URL="postgres://user:pass@localhost:5432/mydb" \
npx @forestadmin/workflow-executor

Variable	Required	Description
`FOREST_ENV_SECRET`	yes	Your environment secret — same value as your agent. Also in app.forestadmin.com → Settings → Environments.
`FOREST_AUTH_SECRET`	yes	The same `authSecret` value your agent is configured with — ask whoever operates the agent.
`AGENT_URL`	yes	URL where your Forest Admin agent is running (e.g. `http://localhost:3351`).
`DATABASE_URL`	yes	Postgres connection string. Required unless you pass the `--in-memory` flag (testing only — state is lost on restart).

When Forest Runtime runs in Docker and your agent runs on the host machine, use host.docker.internal instead of localhost in AGENT_URL and DATABASE_URL. On Linux Docker Engine that hostname doesn’t exist by default, so the --add-host=host.docker.internal:host-gateway flag above is required to resolve it (on Docker Desktop it’s already provided and the flag is harmless).

Network requirements

A standalone Forest Runtime opens these connections (an embedded executor makes the same outbound calls from the agent process, with no extra inbound port):

Direction	Flow	Purpose
Inbound	Agent → Forest Runtime `:3400`	The agent forwards workflow requests.
Outbound	Forest Runtime → `api.forestadmin.com` (HTTPS)	Polling the orchestrator for pending steps.
Outbound	Forest Runtime → `AGENT_URL`	Data steps read/write through your agent.
Outbound	Forest Runtime → your Postgres	State persistence.
Outbound	Forest Runtime → LLM provider & remote MCP tools	AI steps and MCP Tasks (Forest’s AI server by default, or your own provider — see AI provider).

On first boot Forest Runtime auto-creates its workflow_step_executions table, then polls the orchestrator every 30 seconds (POLLING_INTERVAL_S) for work. Forest Runtime is stateless apart from its Postgres database: you can run several instances against the same database for high availability — each pending step is claimed by exactly one instance. If you use OAuth-protected MCP connectors, give every instance the same encryption key.

Health check

GET /health is public (no auth) and returns the runtime’s current state:

curl http://localhost:3400/health
# {"state":"running"}

State	HTTP	Meaning
`running`	`200`	Started and polling for work.
`draining`	`200`	Graceful shutdown — finishing in-flight steps (up to `STOP_TIMEOUT_S`, 30s by default), no longer taking new runs.
`idle`	`503`	Not started yet.
`stopped`	`503`	Shut down.

For liveness probes, treat any 200 as healthy. For readiness probes, route traffic only on {"state":"running"} so a draining instance stops receiving new work while it finishes in-flight steps.

AI provider

Several step types rely on an LLM: guidance, decisions, MCP Tasks, and AI-assisted data steps. By default Forest Runtime uses Forest’s AI server — no configuration required, AI steps work out of the box. To keep AI calls off Forest’s server and use your own provider and key instead, set all three variables together:

Variable	Description
`AI_PROVIDER`	`anthropic` or `openai`.
`AI_MODEL`	Model name for that provider (e.g. `gpt-4.1`, `claude-sonnet-5`).
`AI_API_KEY`	Your API key for that provider.

This is all-or-nothing: set the three together to use your own provider, or leave all three unset to fall back to Forest’s AI server. Setting only some of them fails at startup.

OAuth-protected MCP connectors

If your workflows include MCP Tasks backed by OAuth-protected connectors, Forest Runtime stores each user’s OAuth credentials in its database, encrypted at rest. Provide the encryption key:

Variable	Description
`FOREST_EXECUTOR_ENCRYPTION_KEY`	At-rest encryption key (AES-256-GCM) for stored OAuth credentials. Generate with `openssl rand -hex 32`. Use a separate secret from `FOREST_AUTH_SECRET`.

Required only for OAuth-protected MCP connectors, and read lazily — an instance that stores no such credentials runs fine without it.
Use the same value on every instance that shares a database, or an instance won’t decrypt credentials written by another.
Treat it as permanent: there is no managed rotation. Changing it forces every affected user to reconnect their connectors.

Observability

The Docker image ships with OpenTelemetry APM built in, compatible with any OTLP backend (Datadog, Grafana Tempo, Jaeger, Honeycomb…). It is off by default and turns on as soon as you set OTEL_EXPORTER_OTLP_ENDPOINT. OpenTelemetry is bundled only in the Docker image, not the npm package.

Tuning

Beyond the required variables, these optional knobs have sensible defaults and rarely need changing:

Variable	Default	Description
`HTTP_PORT`	`3400`	Port Forest Runtime’s HTTP server listens on.
`POLLING_INTERVAL_S`	`30`	How often it polls the orchestrator for pending steps.
`LOG_LEVEL`	`Info`	`Debug`, `Info`, `Warn`, or `Error`.
`STEP_TIMEOUT_S`	`300`	Max duration of a single step.
`AI_INVOKE_TIMEOUT_S`	`30`	Max duration of a single AI provider invocation.
`STOP_TIMEOUT_S`	`30`	Grace period on shutdown to finish in-flight steps before exiting.
`MAX_CHAIN_DEPTH`	`50`	Max steps auto-executed per run before yielding.
`SCHEMA_CACHE_TTL_S`	`600`	Collection schema cache TTL.
`DATABASE_SCHEMA`	`forest`	Postgres schema Forest Runtime creates its tables in — already isolated from `public` by default; set it only to use a different name.

For the remaining variables (individual database parts, DATABASE_SSL, in-memory testing mode, full OTel configuration), see the package README on npm.

Overview

Connect

Process

Build

Execute

Collaborate

Manage

Embed

Control

Project Settings

Do I need Forest Runtime?

How it works

Prerequisites

Running Forest Runtime

Embedded in the Node.js agent

Standalone (Docker or CLI)

Network requirements

Health check

AI provider

OAuth-protected MCP connectors

Observability

Tuning

Learn more

Workflows overview

MCP Servers

​Do I need Forest Runtime?

​How it works

​Prerequisites

​Running Forest Runtime

​Embedded in the Node.js agent

​Standalone (Docker or CLI)

​Network requirements

​Health check

​AI provider

​OAuth-protected MCP connectors

​Observability

​Tuning

​Learn more

Workflows overview

MCP Servers

Do I need Forest Runtime?

How it works

Prerequisites

Running Forest Runtime

Embedded in the Node.js agent

Standalone (Docker or CLI)

Network requirements

Health check

AI provider

OAuth-protected MCP connectors

Observability

Tuning

Learn more