Skip to main content
How-to guideApplies to: Unified engine deployments
The configuration file tells Unified which services to start, where to store data, and how to run work. Laminar reads this TOML file and checks its values before starting those services. The console’s Settings page shows the available fields and their current values. The reference below explains each setting, including fields used only with a particular worker provider or storage type.

​
Read the field reference

Each top-level setting has its own page. Field names on a page are relative to its config group. For example, flush_interval on the Database page means database.flush_interval. <name> is a name you choose for a map entry. [] marks an array entry. Read the short explanation and default first. Expand Example when you want to see what changing the value does.

​
Services and features

  • mode and network: Controller or worker mode and connection addresses.
  • availability: Startup, activation, health checks, and draining.
  • agent: Assistant model connection and turn limits.
  • feature_flags: Permissions for assistant actions, notebooks, and schedules.
  • workspace: Saved query and workspace document limits.
  • dashboards: Dashboard definitions, refresh checks, and result cleanup.
  • ui_path: Built UI files served by the engine.

​
Storage and sources

​
Workers and execution

​
Clients and notebooks

  • http_api: Browser/API listener, request limits, and MCP access.
  • spark_connect: Spark Connect listener and protocol limits.
  • session: SQL session defaults, history, and uploaded artifacts.
  • driver_limits: Workload graph and status limits.
  • result_read_limits: Result pages and continuation-token limits.
  • notebooks: Notebook runs, Python processes, and output limits.

​
Telemetry

  • telemetry: Logs, metrics, traces, export, and saved history.
Each field entry explains what the setting controls and gives a concrete example of its effect. It also lists the value type and what happens when you leave the field out. Examples show possible configurations; they are not extra defaults or values you must copy. Defaults describe the engine in this release before desktop setup or platform configuration changes its settings. For example, a platform deployment may use a different port from the native default. Use Settings to see the values used by your running engine. Set when used means there is no value in the native baseline for that provider or named entry. Supply the fields needed by the selected variant. Unset means the optional value is absent. The text explains whether that disables a feature, leaves a limit open, or selects another configured value. Empty maps and arrays contain no configured entries. Byte values are integer bytes unless a field states another unit. CPU values use millicores: 1000 is one CPU. Durations use whole seconds plus additional nanoseconds:
The second example is 100 milliseconds. Every duration in the reference accepts these two fields; nanos must be below one billion. TOML has no null value. Omit an optional field to leave it unset. A zero value has a special meaning only where the reference states one.

​
Choose the configuration file

  • Bare launch on macOS: Creates a workspace config under ~/Library/Application Support/Laminar if missing.
  • LAMINAR_HOME=/absolute/path laminar: Creates or uses that workspace’s config.toml.
  • laminar --config /path/engine.toml: Reads exactly that file; does not apply desktop workspace setup.
  • laminar --roles ...: Uses defaults or the explicit file, then replaces its hosted roles; does not apply desktop setup.
Relative file and directory paths in an explicit config use the process working directory. Use absolute paths for a service that may start from another directory. An existing workspace config is not replaced during startup.

​
Defaults and precedence

The load order is engine defaults, values from the selected file, then supported command options. --mode selects controller or allocated worker mode. --allow-config-edit enables saving through Settings when a config file is available. There is no general LAMINAR_* mapping for every config field, no automatic ${VARIABLE} substitution in TOML strings, and no automatic merge of multiple config files. Environment access is specific to features such as the local workspace, allocation input, and credential providers. storage_root is required in a config file. Other omitted fields use defaults, including fields inside nested sections. Set only the values you want to change. Settings shows the full effective configuration. Saves and exports contain the values that differ from defaults. workers.provisioners.<name>.provider selects in_process, local_process, docker, kubernetes, or lambda. Each entry holds its own provider settings. Set workers.default_provisioner when more than one is defined. Define named resource sizes in workers.profiles, then select them on a workload or task.

​
Disabled features

For agent, a disabled section can contain only its switch:
Their remaining fields are not needed to start a disabled feature. The parser fills omitted values internally. If you keep other fields in a disabled section, those values must still parse and pass applicable validation. A feature permission such as feature_flags.notebooks.execution.python = true does not create its required service or runtime.

​
Configuration in the combined platform host

The platform command reads its YAML configuration:
Add a unified map to enable Unified. It contains native Unified configuration fields. The host passes the resulting configuration to Unified in the same process. To load an independent Unified file, set:
The file must be mounted in the controller. Additional inline fields in the unified map override the loaded file. Set storage_root in that file, or set unified.storage_root inline. In platform mode the host serves Unified through its shared HTTP listener. Unified service RPC, worker connections, and telemetry history still use their own configured addresses. A compute setting does not add Kubernetes Service ports or permissions.

​
Process modes and addresses

Controller mode hosts all controller services locally. Worker mode receives generated configuration and allocation input at launch. Set internal listeners and advertised worker URLs under network.services, network.workers, and network.telemetry. Client listeners use network.http and network.spark_connect. Users maintain one controller file. The controller supplies worker runtime settings and endpoints. Independent controller-service deployment is no longer supported.

​
Settings and file access

An automatically created workspace config is editable through Settings. An explicit config is read-only there unless started with:
The engine user needs permission to write that file. Validation checks the proposed values before saving. Saving a new file does not rebuild running services. Deployment changes require starting the engine with the saved configuration before they take effect. Feature flag controls have their own behavior and do not replace this startup configuration. Keep secret values in the configured secret provider where possible. Command options and file exports are not a general-purpose secret distribution mechanism. See networking and security.
Last modified on November 4, 2026