feat: add workflow executor doc

[arnaud-moncel]

Add Forest Runtime documentation for self-hosted workflow execution

Adds a new forest-runtime.mdx page to the workflows docs section covering how to run workflow steps on self-hosted infrastructure via the Forest Runtime agent. The page includes setup prerequisites, Docker and npx run instructions, required environment variables, OAuth/MCP connector configuration, OpenTelemetry observability guidance, and a health check endpoint reference.

Changes since #15 opened

• Clarified data boundary behavior to emphasize that the orchestrator never sees records and data for data steps remains within user infrastructure, added warning about AI-powered steps and MCP Tasks potentially sending prompt content to external services, and updated usage guidance to reflect that Forest Runtime localizes data steps but does not make workflows fully air-gapped [5e46f07]
• Updated agent version prerequisites to require @forestadmin/agent version 1.79.0 or higher for Node and forest_admin_rails version 1.31.0 or higher for Ruby, with clarification on configuring the executor URL [5e46f07]
• Changed DATABASE_URL requirement from a production-only note to an explicit requirement unless using the --in-memory flag, with clarification that in-memory mode is for testing only and state is lost on restart [5e46f07]
• Added documentation for /health endpoint behavior, specifying it returns 200 for running and draining states and 503 before ready state, with guidance on liveness versus readiness probe usage [5e46f07]
• Corrected polling interval description from 5 seconds to 30 seconds and updated reference to POLLING_INTERVAL_S environment variable [5e46f07]
• Added AI provider configuration section describing default behavior using Forest's AI server and instructions for configuring custom providers via AI_PROVIDER, AI_MODEL, and AI_API_KEY environment variables with all-or-nothing requirement [5e46f07]
• Added tuning section listing optional environment variables with their default values including HTTP_PORT, POLLING_INTERVAL_S, LOG_LEVEL, STEP_TIMEOUT_S, AI_INVOKE_TIMEOUT_S, STOP_TIMEOUT_S, MAX_CHAIN_DEPTH, SCHEMA_CACHE_TTL_S, and FOREST_SERVER_URL [5e46f07]
• Updated final note to reference remaining environment variables and clarify OpenTelemetry configuration scope [5e46f07]
• Added migration documentation section for transitioning workflow execution from browser-based tabs to Forest Runtime orchestrator [e0ff5d4]
• Rewrote the 'Migrating from browser execution' section in the Forest Runtime documentation [59717e5]
• Clarified that the orchestrator coordinates workflows while Forest Runtime executes steps on customer infrastructure, removed the note describing Forest Runtime as optional and self-hosted, and removed the statement that workflows run on Forest's managed orchestrator without it [893c2f7]
• Updated migration documentation to emphasize workflows require no rebuild or reconfiguration, removed guidance about rolling back to browser execution, and added notice that browser execution is being retired with support contact information for pausing migration [893c2f7]
• Rewrote the 'Do I need Forest Runtime?' section in the forest-runtime.mdx workflow documentation [f6abe96]
• Added documentation explaining Forest Runtime requirement for webhook-triggered workflows [a51cc86]
• Added documentation page at /product/process/workflows/triggers explaining workflow triggers including manual and webhook-based triggers, webhook availability across environments, separation of stable webhook URL from bearer token-based execution identity, webhook enablement steps, UI details for URL copying and JSON body hints with regenerate URL functionality, URL regeneration and immediate invalidation behavior, revocation mechanisms and their HTTP response codes (404/400/401), and audit trail marking for webhook-triggered runs [a048ca7]
• Added API reference documentation at /reference/api/endpoints/trigger-workflow-webhook for triggering workflows via webhook POST requests to a copied signed webhook URL [a048ca7]
• Added navigation routes product/process/workflows/triggers and reference/api/endpoints/trigger-workflow-webhook to the documentation structure in docs.json [a048ca7]
• Added note in /reference/api/introduction explaining that the trigger workflow via webhook endpoint does not follow the base URL/path convention and requires copying the full signed URL from trigger settings [a048ca7]
• Updated workflow documentation pages to reference the new triggers documentation including adding a sentence in /product/execute/workflows about automatic workflow starts via webhook, updating a bolded sentence in /product/process/workflows/forest-runtime to link to trigger documentation, and adding a 'Triggering workflows' section in /product/process/workflows/overview describing manual and webhook-based starts with a Card component linking to trigger management guidance [a048ca7]
• Added image assets images/workflows/webhook-regenerate-url.png and images/workflows/webhook-trigger-rows.png to support the workflow triggers documentation [a048ca7]
• Revised orchestrator data boundaries paragraph in workflow runtime documentation [0753220]
• Replaced Warning block with Note block for AI step exceptions in workflow runtime documentation [0753220]
• Added documentation for DATABASE_SCHEMA environment variable in the forest runtime workflow executor configuration table [4814751]
• Restructured health check documentation for GET /health endpoint by adding a dedicated section header, replacing the Note block with a markdown table enumerating runtime states (running, draining, idle, stopped) with their HTTP codes and meanings, moving liveness/readiness guidance to a paragraph, and updating the internal reference link from #running-forest-runtime to #health-check in migration instructions [3c4ad14]
• Reworded front-matter description to emphasize that the Forest orchestrator never sees customer records [121be32]
• Updated workflow trigger documentation to include webhook-triggered workflows alongside user-triggered workflows [121be32]
• Added first boot behavior documentation for Forest Runtime including auto-creation of tables and 30-second polling interval [121be32]
• Clarified networking documentation to explicitly reference Forest Runtime's HTTP port in agent-to-runtime communication [121be32]
• Updated configuration table descriptions to consistently reference 'Forest Runtime' instead of 'executor' and clarified HTTP_PORT and FOREST_SERVER_URL descriptions [121be32]
• Rewrote execution model documentation to clarify Forest Runtime executes workflow steps server-side and added Mermaid diagram illustrating orchestrator-to-runtime-to-agent/database communication flows [3d54a7c]
• Added network requirements section documenting inbound and outbound port/host flows including LLM and MCP egress requirements [3d54a7c]
• Added migration prerequisites section defining developer, ops, and Forest responsibilities for transitioning from browser execution [3d54a7c]
• Enhanced runtime architecture description to document stateless design, multi-instance support against shared Postgres, and OAuth encryption key requirements for MCP connectors [3d54a7c]
• Clarified FOREST_AUTH_SECRET environment variable documentation to reference agent's configured authSecret and operator responsibility [3d54a7c]
• Updated AI provider section to enumerate step types relying on LLM while maintaining default provider behavior [3d54a7c]
• Removed FOREST_SERVER_URL from optional environment variables table [3d54a7c]
• Applied minor phrasing and consistency edits across multiple paragraphs and notes [3d54a7c]
• Added Forest Runtime's Postgres state database node and connection in workflow executor documentation [1ceadea]
• Updated business database node label in workflow executor documentation [1ceadea]
• Removed prerequisite about Forest switching legacy environments over on request from the Forest Runtime setup documentation [11695e6]
• Updated Forest Runtime setup prerequisites documentation to clarify deployment responsibilities and add workflow executor URL reference [11695e6]
• Removed explanatory block describing developer and ops roles for Forest Runtime setup from Prerequisites section [9251ce9]
• Added embedded mode documentation for running workflow executor within the Node.js agent [35a5d9d]
• Restructured standalone workflow executor documentation into a two-step deployment flow [35a5d9d]
• Expanded prerequisites section with version dependencies and database requirements [35a5d9d]
• Clarified network requirements for both embedded and standalone workflow executor modes [35a5d9d]
• Rewrote Note block in embedded executor section to clarify configuration scope and standalone usage requirements [13a17a9]
• Updated database option documentation in forest-runtime.mdx to specify Sequelize options support for schema isolation [457e51e]
• Rewrote Note section in forest-runtime.mdx to document embedded runtime mode configuration constraints and environment variable requirements [457e51e]
• Added encryptionKey configuration option to embedded executor options table [a1f8264]
• Updated Note section to remove specific environment-based configuration references [a1f8264]
• Replaced separate pollingIntervalS and stepTimeoutS configuration rows with an ai row for bring-your-own LLM parameters and a consolidated row listing multiple tuning knobs (pollingIntervalS, stepTimeoutS, aiInvokeTimeoutS, stopTimeoutS, maxChainDepth, schemaCacheTtlS, loggerLevel) in camelCase format that mirror standalone defaults for the embedded executor configuration [d4bc7d4]
• Revised the Note section to state embedded executor now has full configuration parity with standalone executor, including custom AI provider (ai), encryption key, and all tuning knobs, removing the previous claim that embedded always uses Forest's AI server and defaults [d4bc7d4]
• Removed loggerLevel from embedded executor tuning knob configuration options and added clarification that log verbosity follows the agent's logger without a separate log-level option for embedded mode [d444e2f]
• Added compatibility table documenting agent support for workflow executor configuration [88a29f3]
• Expanded code examples to cover all supported agent generations [88a29f3]
• Updated standalone deployment section to clarify usage scenarios and agent integration mechanics [88a29f3]
• Added documentation note regarding Python agent compatibility [88a29f3]
• Removed the 'Migrating from browser execution' section from the workflow executor documentation [a692a9f]

^{Macroscope summarized d2dabfa.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
forest	🟢 Ready	View Preview	Jul 20, 2026, 9:08 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[macroscopeapp]

🟡 Medium workflows/forest-runtime.mdx:62

The npx @forestadmin/workflow-executor instructions don't mention the Node.js version requirement, so users on older Node versions will get an install or startup failure instead of a working runtime — the package requires Node.js >= 22.12.0. Consider adding the minimum Node version next to the npx command.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @product/process/workflows/forest-runtime.mdx around line 62:

The `npx @forestadmin/workflow-executor` instructions don't mention the Node.js version requirement, so users on older Node versions will get an install or startup failure instead of a working runtime — the package requires Node.js >= 22.12.0. Consider adding the minimum Node version next to the `npx` command.

[Scra3]

Reviewed against the workflow-executor source (agent-nodejs) and the Ruby agent. Technically accurate throughout — env vars, port 3400, /health body, the auto-created workflow_step_executions table, the workflowExecutorUrl/config.workflow_executor_url options (both Node and Rails confirmed), AES-256-GCM + openssl rand -hex 32, and the ghcr image all match the code. One factual fix below.

[Scra3]

Second pass — coverage gaps checked against agent-nodejs origin/main and the Forest architecture (flow F6 / AI plane / v1-v2 parity). The privacy framing (top comment) is the important one for a data-residency page.

[Scra3]

question: the CodeGroup covers v2 Node + Rails, but workflowExecutorUrl also exists in v1 forest-express and agent-python support is unclear — which SDKs/generations are actually supported?

[Scra3]

Final sweep — internal links, docs.json placement, the JWT-relay claim, and the 3351 port example all check out against the code. One last improvement below.

[Scra3]

Re-reviewed the fixes (5e46f07): all previous findings are addressed, and the two new claims check out against the code — the Forest AI server fallback is real (ServerAiAdapter when AI_PROVIDER is unset) and the read/update data steps do go through the AI port. One last thing before merge: the frontmatter description (line 3) still says 'no client data ever leaves your network', contradicting the body's Warning — Macroscope's suggestion on it is good to take. LGTM once that lands.

[macroscopeapp]

🟡 Medium workflows/forest-runtime.mdx:63

The Docker and npx examples set DATABASE_URL to a local Postgres connection (localhost:5432 / host.docker.internal:5432) without DATABASE_SSL=false. Since the executor defaults DATABASE_SSL to true, these commands fail to boot against a typical local Postgres that doesn't accept TLS. Add DATABASE_SSL=false to both examples (or point them at a TLS-enabled database).

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_SSL=false \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/mydb" \
  -p 3400:3400 \
  ghcr.io/forestadmin/workflow-executor:latest

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @product/process/workflows/forest-runtime.mdx around lines 63-71:

The Docker and `npx` examples set `DATABASE_URL` to a local Postgres connection (`localhost:5432` / `host.docker.internal:5432`) without `DATABASE_SSL=false`. Since the executor defaults `DATABASE_SSL` to `true`, these commands fail to boot against a typical local Postgres that doesn't accept TLS. Add `DATABASE_SSL=false` to both examples (or point them at a TLS-enabled database).

[macroscopeapp]

🟠 High workflows/forest-runtime.mdx:48

The embedded setup instructions tell users to add .addWorkflowExecutor(...) after upgrading @forestadmin/agent but never mention installing @forestadmin/workflow-executor. In @forestadmin/agent that package is an optional peer dependency that addWorkflowExecutor() dynamically imports, so a project that only follows the documented steps will fail during start() with a missing-dependency error. Add an explicit npm install @forestadmin/workflow-executor (at a compatible version) before the code example.

Suggested change

	Requires **`@forestadmin/agent` ≥ 1.84.0**. Add one line — the executor runs inside the agent process, so there is nothing else to deploy:
	### Embedded in the Node.js agent
	Requires **`@forestadmin/agent` ≥ 1.84.0** and **`@forestadmin/workflow-executor`** (an optional peer dependency that is dynamically imported — install it explicitly):
	```bash
	npm install @forestadmin/workflow-executor

Add one line — the executor runs inside the agent process, so there is nothing else to deploy:

<details>
<summary>🚀 Reply "<strong>fix it for me</strong>" or copy this <strong>AI Prompt</strong> for your agent:</summary>

```text
In file @product/process/workflows/forest-runtime.mdx around lines 48-49:

The embedded setup instructions tell users to add `.addWorkflowExecutor(...)` after upgrading `@forestadmin/agent` but never mention installing `@forestadmin/workflow-executor`. In `@forestadmin/agent` that package is an optional peer dependency that `addWorkflowExecutor()` dynamically imports, so a project that only follows the documented steps will fail during `start()` with a missing-dependency error. Add an explicit `npm install @forestadmin/workflow-executor` (at a compatible version) before the code example.

[macroscopeapp]

🟠 High workflows/forest-runtime.mdx:68

The embedded options table documents an encryptionKey field, but the embedded executor has no such option in its TypeScript interface and never reads it. Code following this guidance fails TypeScript compilation (the encryptionKey property is rejected) and does not configure OAuth credential encryption, so OAuth-protected MCP connectors still fail when they need the key. Either remove this row and point embedded users to the FOREST_EXECUTOR_ENCRYPTION_KEY environment variable, or add the option to the agent before documenting it.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @product/process/workflows/forest-runtime.mdx around line 68:

The embedded options table documents an `encryptionKey` field, but the embedded executor has no such option in its TypeScript interface and never reads it. Code following this guidance fails TypeScript compilation (the `encryptionKey` property is rejected) and does not configure OAuth credential encryption, so OAuth-protected MCP connectors still fail when they need the key. Either remove this row and point embedded users to the `FOREST_EXECUTOR_ENCRYPTION_KEY` environment variable, or add the option to the agent before documenting it.

[macroscopeapp]

🟡 Medium workflows/forest-runtime.mdx:68

The embedded-options table on line 68 lists aiInvokeTimeoutS, stopTimeoutS, maxChainDepth, schemaCacheTtlS, and loggerLevel as supported, but these options are silently ignored — the runtime keeps its defaults. The "full configuration parity" note in the following <Note> is therefore also incorrect. Either wire these fields through in WorkflowExecutorEmbedOptions / EmbeddedWorkflowExecutor.start(), or remove the unsupported options from the table and drop the parity claim.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @product/process/workflows/forest-runtime.mdx around line 68:

The embedded-options table on line 68 lists `aiInvokeTimeoutS`, `stopTimeoutS`, `maxChainDepth`, `schemaCacheTtlS`, and `loggerLevel` as supported, but these options are silently ignored — the runtime keeps its defaults. The "full configuration parity" note in the following `<Note>` is therefore also incorrect. Either wire these fields through in `WorkflowExecutorEmbedOptions` / `EmbeddedWorkflowExecutor.start()`, or remove the unsupported options from the table and drop the parity claim.