Configuration reference

Values below are environment variables unless noted. Empty optional secrets disable the related capability.

Server

Variable	Default	Purpose
HOST	127.0.0.1	Listen address; Compose uses 0.0.0.0
PORT	3000	Listen port
LOG_LEVEL	info	Fastify and workflow log level
WORKSPACE_SOURCES	current directory source	JSON array of { id, path, priority, readonly, writeTarget? } workspace sources
WORKSPACE_DISCOVERY_MODE	strict	strict fails startup for invalid workflows/drivers; degraded skips invalid packages and reports them through /ready
RUN_DATA_DIR	current directory data	Default directory for SQLite files and generated driver dependency caches
ASYNC_RUN_CONCURRENCY	1	Maximum simultaneous durable runs
ASYNC_RUN_RETENTION_DAYS	7	Retention period for terminal run records
ASYNC_CALLBACK_ALLOWED_HOSTS	empty	Comma-separated exact or wildcard HTTPS callback hosts
ASYNC_CALLBACK_SECRET	empty	Completion callback HMAC secret
WORKFLOW_RUNNERS	empty	JSON array of authenticated remote runner definitions
TRUSTED_IDENTITY_HEADER	empty	Identity header accepted only from a trusted reverse proxy
APPLICATION_API_KEY	required outside tests	Bearer token for application API and webhook execution requests
CHANNEL_ID	channel-host	Local channel runtime identity
CHANNEL_SECRET	development placeholder	Channel-host API and callback HMAC secret; at least 16 characters when channels are enabled
CHANNEL_SECRET_KEY	unset	Base64-encoded 32-byte key that enables the default encrypted channel store
CHANNEL_DATA_FILE	RUN_DATA_DIR/channels.sqlite	Channel instance and encrypted credential database
CHANNEL_DATA_DIR	RUN_DATA_DIR/channels	Per-instance channel driver data
CHANNEL_INTEGRATIONS	[]	JSON array of fixed { id, secret, callbackUrl } integration definitions
WORKSPACE_DRIVER_DEPENDENCY_ROOT	automatic cache	Explicit preinstalled dependency tree; bypasses automatic locked dependency installation

NODE_ENV=test selects in-memory databases, silent logging, and a test API key in server test paths. Workflow HTTP secret names and ${NAME} references in workspace configuration resolve from the server environment. These names are application-defined rather than dedicated server settings. The stock workspace does not require any workflow or AI-provider secrets because its provider and model registries are empty.

ASYNC_RUN_CONCURRENCY sets the maximum number of active durable runs. Additional accepted async runs stay queued until a slot is available. ASYNC_RUN_RETENTION_DAYS controls terminal run cleanup.

Workspace discovery runs at startup. The default strict mode requires all configured workflows and drivers to load. WORKSPACE_DISCOVERY_MODE=degraded keeps healthy packages available, logs each skipped package, and returns HTTP 503 from /ready with sanitized issue summaries.

WORKSPACE_SOURCES is a non-empty JSON array. Relative source paths resolve from the server's current working directory. For example, an application can override selected definitions from a read-only base workspace:

WORKSPACE_SOURCES=[{"id":"application","path":"./workspace","priority":100,"readonly":false,"writeTarget":true},{"id":"builtin","path":"./builtin-workspace","priority":0,"readonly":true}]

Sources are ordered by numeric priority, with higher values winning per workflow ID, configuration record name, or driver kind/type. Defining the same identity in equal-priority sources fails startup. A higher-priority definition claims that identity even when it is invalid, so degraded discovery skips it instead of falling back to a lower-priority definition. Sources may be partial and omit any workspace subdirectory or configuration file.

writeTarget is optional. At most one non-read-only source may set it to true, and that source must have strictly higher priority than every other source. With no write target, configuration-store mutations are disabled; loading and workflow execution remain available. When WORKSPACE_SOURCES is absent, the current directory is used as a writable application source with priority 0.

Workspace configuration

The server loads any present config/providers.yaml, config/models.yaml, config/toolsets.yaml, and config/memories.yaml from each workspace source during startup. Present files must use version: 1; missing files contribute no records. Provider entries configure loaded provider driver types, model entries map semantic roles to named providers, toolsets configure MCP endpoints and per-tool policy, and memories configure loaded memory driver types. Model configuration values override provider values with the same key. If any models are configured, the general role is required.

Model configuration is role-first by design. Workflows and built-in AI nodes request semantic (logical) roles, and this file binds those roles to concrete provider/model combinations for the current deployment. Keep provider-specific model IDs in this file, not in workflow YAML.

All YAML string values support ${NAME} environment references. References can appear inside larger strings, and $${NAME} produces a literal ${NAME}. A referenced variable must be defined; an empty defined value remains empty and may then fail driver validation. Configuration and driver instances are loaded once at startup. Current model, memory, and toolset HTTP endpoints expose the startup snapshot and do not edit or reload these files. Layered records expose origin: { sourceId, readonly } so clients can identify the source that supplied the effective definition.

The stock repository workspace leaves all four registries empty. The provider and memory examples below are structural examples and work only when the matching workspace drivers are installed.

providers.yaml

version: 1
providers:
  openrouter:
    type: openrouter
    config:
      apiKey: ${OPENROUTER_API_KEY}

models.yaml

version: 1
models:
  general:
    provider: openrouter
    config:
      model: ${OPENROUTER_MODEL}
  summarization:
    provider: openrouter
    config:
      model: ${OPENROUTER_SUMMARIZATION_MODEL}
  router:
    provider: openrouter
    config:
      model: ${OPENROUTER_ROUTER_MODEL}

The example above maps multiple semantic roles to provider-backed model definitions. Role names are stable workflow contracts; mapped models can differ across environments without changing workflow files.

toolsets.yaml

version: 1
toolsets:
  accounting_data:
    label: Accounting data
    enabled: true
    provider:
      type: mcp-streamable-http
      endpointUrl: http://filesystem-mcp:8080/mcp
      authToken: ${ACCOUNTING_MCP_TOKEN}
    policies:
      read_ledger: allow
      post_document: ask

memories.yaml

version: 1
memories: {}

Each configured memory has type, optional description, and config. Both the accepted config keys and the resulting memory kind come from the loaded driver; Faimulus does not provide a built-in file memory driver.

Configuration versioning

Each workspace config file has its own root schema version. Current server releases require version: 1 for every file and reject mismatches during startup with a validation error.

Memory

The stock server contains no memory or provider drivers. Applications place trusted TypeScript drivers below a source's drivers/<memory|provider|channel>/<name> directory. Each driver directory requires manifest.yaml with a relative TypeScript entrypoint and may contain package.json. A configured provider or memory whose type was not loaded makes startup fail with an explicit unknown-driver error.

The server validates and compiles drivers once at startup. In strict discovery mode any invalid driver prevents startup; in degraded mode invalid drivers are skipped, logged, and reported by /ready. Third-party dependencies belong in per-driver package.json files and must be represented by the shared drivers/package.json and drivers/package-lock.json. The server runs npm ci --omit=dev into a content-addressed cache unless WORKSPACE_DRIVER_DEPENDENCY_ROOT is set.

Memory definitions and their safe configuration are read-only in the management API and web UI. Workflow nodes may write through drivers that permit it. Applications should overlay writable memory paths with a volume when the rest of the workspace is mounted read-only.

The docs image uses the DOCS_BASE Docker build argument, not a runtime environment variable.

Other values in .env.example may be consumed by workflow secrets, workspace drivers, or adjacent integration services. They are not server settings unless referenced by deployed workspace configuration.