> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forest.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Forest Runtime
> Run your workflow steps on your own infrastructure — the Forest orchestrator never sees your records.
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.
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](#ai-provider).
## Do I need Forest Runtime?
Yes — Forest Runtime is what executes your workflow steps. **[Webhook-triggered workflows](/product/process/workflows/triggers) especially**: a webhook can fire at any time, with no guarantee anyone has Forest open in a browser, so they can only run server-side.
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
1. A workflow is triggered — by a user or a [webhook](/product/process/workflows/triggers). The Forest orchestrator queues the pending steps.
2. Forest Runtime polls the orchestrator and pulls the steps assigned to it.
3. Each step runs locally, reaching your data and actions through your Forest agent.
4. It reports the step outcome back to the orchestrator, which advances the workflow.
```mermaid theme={null}
flowchart LR
O["Forest orchestrator
(coordinates)"] -- "pending steps" --> R["Forest Runtime
(your infrastructure)"]
R -- "data & actions" --> A["Your Forest agent"] --> DB[("Your business
database")]
R -. "state (DATABASE_URL)" .-> P[("Forest Runtime's
Postgres")]
R -- "outcomes only, never records" --> O
```
## 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](#embedded-in-the-nodejs-agent)** — one line in your agent, nothing separate to deploy. The simplest option.
* **[Standalone](#standalone-docker-or-cli)** — 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
Requires **`@forestadmin/agent` ≥ 1.84.0**. Add one line — the executor runs inside the agent process, so there is nothing else to deploy:
```js theme={null}
createAgent(options)
.addDataSource(/* ... */)
.addWorkflowExecutor({ database: { uri: process.env.DATABASE_URL } })
.start();
```
It inherits your agent's secrets and Forest connection, so you only configure:
| Option | Description |
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `database` | Postgres connection — a URI or Sequelize options (pass a `schema` here to isolate its tables). Persists run state. 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](#oauth-protected-mcp-connectors) 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](#tuning), 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](#embedded-in-the-nodejs-agent) 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 |
```js Node.js (v2) theme={null}
createAgent({
// ...
workflowExecutorUrl: process.env.WORKFLOW_EXECUTOR_URL, // e.g. http://localhost:3400
})
```
```js forest-express (v1) theme={null}
Liana.init({
// ...
workflowExecutorUrl: process.env.WORKFLOW_EXECUTOR_URL,
})
```
```ruby forest_admin_rails (v2) theme={null}
# config/initializers/forest_admin_rails.rb
ForestAdminRails.configure do |config|
# ...
config.workflow_executor_url = ENV['WORKFLOW_EXECUTOR_URL']
end
```
```ruby forest-rails (v1) theme={null}
# 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:
```bash Docker theme={null}
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
```
```bash npx theme={null}
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](https://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](#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](#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:
```bash theme={null}
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](/product/process/workflows/overview) 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](https://opentelemetry.io/) 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 — set it to isolate them in a shared database. |
For the remaining variables (individual database parts, `DATABASE_SSL`, in-memory testing mode, full OTel configuration), see the package [README on npm](https://www.npmjs.com/package/@forestadmin/workflow-executor).
## Learn more
Build and manage workflows in the no-code editor
Configure the connectors used by MCP Tasks