reference configuration

Configuration

Active contributors: Zachary Bensalem

Fleet RLM Lite resolves one process-wide FleetSettings object at startup from a schema 4 TOML file, .env, and the process environment. The object validates types and cross-field constraints, records which source supplied each field, and reports a non-secret projection through /config and the CLI. Settings are frozen once the process starts; file changes require a restart.

Key source files

Path	Responsibility
src/fleet_rlm/config.py	FleetSettings, TOML loading, source precedence, validators, model construction, MLflow target resolution, and get_settings.
config/fleet.toml	Checked-in non-secret defaults, schema 4.
src/fleet_rlm/api/routes/sessions.py	Serves the session-scoped /config payload.
src/fleet_rlm/tui/commands.py	Formats /config and /settings output in the terminal client.
src/fleet_rlm/session.py	Applies persisted per-session mode and model overrides.
docs/reference/configuration.md	Maintained user-facing configuration reference.

Precedence and loading

Sources are ordered from lowest to highest priority:

1. Built-in field defaults in FleetSettings.
2. The TOML file selected by FLEET_CONFIG, defaulting to config/fleet.toml relative to the working directory.
3. .env in the working directory.
4. The process environment.
5. Explicit overrides passed to FleetSettings(**values) or applied by the CLI with with_explicit_overrides.

settings_customise_sources implements this order explicitly and deliberately excludes file-secret sources. Credentials therefore come only from explicit input, the environment, or .env; no TOML table can set them.

The loader does not search parent directories, interpolate environment variables, or watch for changes. A missing default file is allowed so the process can run on environment values alone. A file named by FLEET_CONFIG must exist and parse as TOML, otherwise startup fails. Every file must contain [config] with the integer schema_version = 4. Schema 3 files with a flat [mlflow] table are rejected with a migration message.

The mapping from TOML table and key to setting field is a single explicit table in src/fleet_rlm/config.py (_TOML_FIELDS). Unknown tables, unknown keys, wrong value types, and environment-only keys placed in TOML all raise ValueError and prevent startup. Values are validated strictly against the field annotation before being merged.

Schema 4 TOML

The checked-in config/fleet.toml is a provisional baseline, not a tuned configuration. It declares these tables:

[config]              schema_version = 4
[runtime]             execution, timeouts, budgets, child and session limits
[llm.root]            root model and generation options
[llm.sub]             sub-agent model and generation options
[llm.reflection]      GEPA reflection model and generation options
[gateway]             optional host / base_url
[decision]            TypeSafe route model
[daytona]             snapshot, idle stop, shared notes, org and Volume IDs
[storage]             upload bound, local directories, database schema, Lakebase endpoint
[mlflow.local]        managed local tracking profile
[mlflow.databricks]   Databricks tracking profile
[evaluation]          judge model
[server]              bind address, port, non-loopback opt-in

[llm] and [mlflow] are parent tables whose children are flattened by the loader. [mlflow] itself must contain only local and databricks child tables, never destination keys directly.

Runtime settings

TOML key	Field	Default (code / TOML)	Purpose
runtime.execution_mode	execution_mode	hybrid / hybrid	One of rlm, flex, hybrid. Strict modes bypass hybrid triage.
runtime.turn_timeout_seconds	turn_timeout_seconds	900 / 900	Turn deadline (10 to 3600 seconds) enforced by the remote-stop watchdog.
runtime.max_llm_calls_per_turn	max_llm_calls_per_turn	150 / 150	Shared model-call budget per Turn, including routing and Skill selection.
runtime.max_agent_depth	max_agent_depth	3 / 3	Maximum recursive child depth (0 to 8); the root counts as zero.
runtime.max_child_sandboxes	max_child_sandboxes	8 / 8	Total child sandbox allocations per Turn (0 to 64).
runtime.max_active_children	max_active_children	4 / 4	Concurrent child capacity (1 to 16). Exhaustion fails immediately.
runtime.max_active_sessions	max_active_sessions	64 / 64	Session runtime registry limit (1 to 1024).
runtime.linked_children	linked_children	true / true	Link child sandboxes to the session root while keeping Volume subpaths separate.

LLM settings

Each role has the same five options. model is required and must use the native gateway route openai/<service-id>. max_tokens and temperature are optional; when omitted the provider controls them. num_retries is 0 to 10. cache is a boolean and is disabled in the checked-in baseline.

TOML key	Field	Default (code / TOML)	Notes
llm.root.model	fleet_root_model	openai/system.ai.deepseek-v4-1-flash / same	Main RLM and serving model.
llm.root.max_tokens	fleet_root_max_tokens	None / 16384	Bounds runaway reasoning; a capped response missing required fields is re-asked once.
llm.root.temperature	fleet_root_temperature	None / omitted	Finite value from 0 to 2.
llm.root.num_retries	fleet_root_num_retries	3 / 3	Retry count.
llm.root.cache	fleet_root_cache	false / false	DSPy response cache for this role.
llm.sub.model	fleet_sub_model	openai/system.ai.claude-sonnet-5-5 / openai/system.ai.deepseek-v4-1-flash	Model used by delegated child agents.
llm.sub.max_tokens	fleet_sub_max_tokens	None / omitted	Optional cap.
llm.sub.temperature	fleet_sub_temperature	None / omitted	Optional sampling temperature.
llm.sub.num_retries	fleet_sub_num_retries	3 / 3	Retry count.
llm.sub.cache	fleet_sub_cache	false / false	Cache flag.
llm.reflection.model	fleet_reflection_model	openai/system.ai.claude-haiku-5-5 / same	GEPA reflection and Flex module rewriting.
llm.reflection.max_tokens	fleet_reflection_max_tokens	None / 32000	Large output budget for rewritten modules.
llm.reflection.temperature	fleet_reflection_temperature	None / 1.0	Optional sampling temperature.
llm.reflection.num_retries	fleet_reflection_num_retries	3 / 3	Also used by the DSPy judge twin.
llm.reflection.cache	fleet_reflection_cache	false / false	Cache flag.

All runtime roles are built with DSPy's native lm15 engine. A model string without the openai/ prefix is rejected rather than routed to another backend.

Gateway and decision settings

TOML key	Field	Default	Purpose
gateway.host	databricks_host	empty	Workspace host; derives https://<host>/ai-gateway/mlflow/v1 when FLEET_LLM_BASE_URL is empty.
gateway.base_url	fleet_llm_base_url	empty	Explicit HTTPS Unity Gateway base URL. HTTP, query strings, fragments, and embedded credentials are rejected.
decision.model	typesafe_model	jev-1.14.0	TypeSafe route-selection model.

The gateway credential is DATABRICKS_TOKEN, read only from the environment or .env. It is a SecretStr and is excluded from configuration reports. TypeSafe uses FLEET_TYPESAFE_API_KEY or TYPESAFE_API_KEY; when absent, the TypeSafe predictor is not constructed.

Daytona settings

TOML key	Field	Default	Purpose
daytona.snapshot	fleet_daytona_snapshot	fleet-rlm-base	Sandbox snapshot name; must be non-empty.
daytona.auto_stop_minutes	daytona_auto_stop_minutes	30	Idle-stop period from 1 to 1440 minutes.
daytona.shared_notes_subpath	fleet_shared_notes_subpath	shared/learned-notes	Volume subpath mounted at /learned on root sandboxes. Empty disables the mount. Must be relative with no .., //, or trailing slash.
daytona.org_id	fleet_daytona_org_id	empty	Daytona organization ID; not a credential.
daytona.volume_id	fleet_daytona_volume_id	empty	Daytona Volume ID; not a credential. A volume name is not a Volume ID.

FLEET_DAYTONA_API_KEY is a credential and therefore environment-only.

Storage settings

TOML key	Field	Default (code / TOML)	Purpose
storage.max_upload_bytes	max_upload_bytes	25000000 / same	Attachment upload bound; the validator caps it at 25 MB.
storage.compiled_program_dir	compiled_program_dir	.fleet/compiled / same	Local compiled program artifacts.
storage.local_skills_dir	local_skills_dir	.fleet/skills / same	User Skill directory used by pull and push.
storage.lakebase_endpoint	fleet_lakebase_endpoint	empty / empty	Lakebase endpoint resource path enabling per-connection Databricks OAuth.
storage.database_schema	fleet_database_schema	public / fleet_rlm_lite	Lowercase PostgreSQL identifier containing Fleet Lite tables.

fleet_database_url and fleet_database_migration_url are credentials and have no TOML key. When a migration DSN is set it must target the same host, port, and database as the runtime DSN. When a Lakebase endpoint is set, both DSNs must require TLS, include host and user, omit embedded passwords, and target the same host and database for migrations.

MLflow local settings

The local profile is the default and is managed by fleet cli.

TOML key	Field	Default	Purpose
mlflow.local.port	mlflow_local_port	5001	Loopback tracking port; the tracking URI is http://127.0.0.1:<port>.
mlflow.local.data_dir	mlflow_local_data_dir	.fleet/mlflow	SQLite metadata and artifact directory.
mlflow.local.experiment_name	mlflow_local_experiment_name	fleet-rlm-dev	Runtime traces.
mlflow.local.eval_experiment_name	mlflow_local_eval_experiment_name	fleet-rlm-eval	Evaluation runs.
mlflow.local.optimization_experiment_name	mlflow_local_optimization_experiment_name	fleet-rlm-gepa	GEPA runs and candidate artifacts.

MLflow Databricks settings

The Databricks profile is selected per command; it is never chosen by an environment default.

TOML key	Field	Default	Purpose
mlflow.databricks.tracking_uri	mlflow_databricks_tracking_uri	databricks	databricks or databricks://<profile>.
mlflow.databricks.experiment_name	mlflow_databricks_experiment_name	/Shared/fleet-rlm-runtime	Runtime experiment; must be an absolute workspace path.
mlflow.databricks.eval_experiment_name	mlflow_databricks_eval_experiment_name	/Shared/fleet-rlm-eval	Evaluation experiment.
mlflow.databricks.optimization_experiment_name	mlflow_databricks_optimization_experiment_name	/Shared/fleet-rlm-gepa	GEPA experiment.
mlflow.databricks.trace_catalog	mlflow_databricks_trace_catalog	uscentral	Unity Catalog catalog for traces.
mlflow.databricks.trace_schema	mlflow_databricks_trace_schema	fleet_observability	Schema for runtime and evaluation traces.
mlflow.databricks.trace_table_prefix	mlflow_databricks_trace_table_prefix	fleet_rlm_runtime	Runtime trace table prefix.
mlflow.databricks.tracing_sql_warehouse_id	mlflow_databricks_tracing_sql_warehouse_id	4d07bd43a3ddfff2	SQL warehouse used for trace export.
mlflow.databricks.optimization_trace_schema	mlflow_databricks_optimization_trace_schema	fleet_gepa	Schema for optimization traces.
mlflow.databricks.optimization_trace_table_prefix	mlflow_databricks_optimization_trace_table_prefix	fleet_rlm_gepa	Optimization trace prefix.
mlflow.databricks.eval_trace_table_prefix	mlflow_databricks_eval_trace_table_prefix	fleet_rlm_eval	Evaluation trace prefix.

In Databricks mode a model validator requires a databricks tracking URI, non-empty catalog, schemas, prefixes, and warehouse ID, and absolute paths for all three experiments. Local and Databricks profiles are resolved independently: mlflow_target() reads only the selected profile and never borrows a value from the other one.

Evaluation and server settings

TOML key	Field	Default	Purpose
evaluation.judge_model	fleet_judge_model	openai:/system.ai.deepseek-v4-1-flash	MLflow judge URI of the form <provider>:/<model>. An openai:/ judge routes through the gateway with DATABRICKS_TOKEN.
server.host	host	127.0.0.1	Bind address.
server.port	port	8000	Bind port.
server.allow_non_loopback_bind	allow_non_loopback_bind	false	Must be true to bind a non-loopback address. It does not authenticate callers.

Environment variables

Every FLEET_* name read by src/fleet_rlm/config.py is listed below. Names are matched case-insensitively by pydantic-settings, so uppercase is the conventional form. The internal mlflow_mode field has the validation alias _fleet_selected_mlflow; it is not a documented FLEET_* environment setting and is selected by the CLI.

Variable	Purpose
FLEET_CONFIG	Path to the TOML file. Defaults to config/fleet.toml.
FLEET_DATABASE_URL	PostgreSQL runtime DSN. Credential; environment or .env only.
FLEET_DATABASE_MIGRATION_URL	Optional DDL-role DSN for migrations. Credential; must target the runtime database.
FLEET_DATABASE_SCHEMA	Lowercase PostgreSQL schema for Fleet Lite tables.
FLEET_LAKEBASE_ENDPOINT	Lakebase endpoint resource path enabling Databricks OAuth credentials.
FLEET_DAYTONA_API_KEY	Daytona API credential.
FLEET_DAYTONA_ORG_ID	Daytona organization ID.
FLEET_DAYTONA_VOLUME_ID	Daytona Volume ID.
FLEET_DAYTONA_SNAPSHOT	Sandbox snapshot name.
FLEET_SHARED_NOTES_SUBPATH	Relative Volume subpath mounted at /learned; empty disables it.
FLEET_DAYTONA_AUTO_STOP_MINUTES	Idle-stop period in minutes. DAYTONA_AUTO_STOP_MINUTES is also accepted.
FLEET_ROOT_MODEL	Root model route.
FLEET_ROOT_MAX_TOKENS	Root output cap (positive integer).
FLEET_ROOT_TEMPERATURE	Root sampling temperature (0 to 2).
FLEET_ROOT_NUM_RETRIES	Root retry count (0 to 10).
FLEET_ROOT_CACHE	Root DSPy cache flag.
FLEET_SUB_MODEL	Sub-agent model route.
FLEET_SUB_MAX_TOKENS	Sub-agent output cap.
FLEET_SUB_TEMPERATURE	Sub-agent temperature.
FLEET_SUB_NUM_RETRIES	Sub-agent retry count.
FLEET_SUB_CACHE	Sub-agent cache flag.
FLEET_REFLECTION_MODEL	Reflection model route.
FLEET_REFLECTION_MAX_TOKENS	Reflection output cap.
FLEET_REFLECTION_TEMPERATURE	Reflection temperature.
FLEET_REFLECTION_NUM_RETRIES	Reflection retry count.
FLEET_REFLECTION_CACHE	Reflection cache flag.
FLEET_JUDGE_MODEL	MLflow judge URI.
FLEET_LLM_BASE_URL	HTTPS Unity Gateway base URL override.
FLEET_TYPESAFE_MODEL	TypeSafe route-selection model.
FLEET_TYPESAFE_API_KEY	TypeSafe credential. TYPESAFE_API_KEY is also accepted.
FLEET_EXECUTION_MODE	rlm, flex, or hybrid.
FLEET_TURN_TIMEOUT_SECONDS	Turn deadline.
FLEET_MAX_LLM_CALLS_PER_TURN	Shared model-call budget. MAX_LLM_CALLS_PER_TURN is also accepted.
FLEET_MAX_AGENT_DEPTH	Maximum child recursion depth.
FLEET_MAX_CHILD_SANDBOXES	Total child sandbox allocations.
FLEET_MAX_ACTIVE_CHILDREN	Concurrent child capacity.
FLEET_MAX_ACTIVE_SESSIONS	Session registry limit. MAX_ACTIVE_SESSIONS is also accepted.
FLEET_LINKED_CHILDREN	Link child sandboxes to the session root.
FLEET_MAX_UPLOAD_BYTES	Attachment upload bound. MAX_UPLOAD_BYTES is also accepted.
FLEET_COMPILED_PROGRAM_DIR	Compiled program directory. COMPILED_PROGRAM_DIR is also accepted.
FLEET_LOCAL_SKILLS_DIR	Local user Skill directory. LOCAL_SKILLS_DIR is also accepted.
FLEET_MLFLOW_LOCAL_PORT	Loopback MLflow port.
FLEET_MLFLOW_LOCAL_DATA_DIR	Local MLflow data directory.
FLEET_MLFLOW_LOCAL_EXPERIMENT_NAME	Local runtime experiment.
FLEET_MLFLOW_LOCAL_EVAL_EXPERIMENT_NAME	Local evaluation experiment.
FLEET_MLFLOW_LOCAL_OPTIMIZATION_EXPERIMENT_NAME	Local GEPA experiment.
FLEET_MLFLOW_DATABRICKS_TRACKING_URI	Databricks tracking URI.
FLEET_MLFLOW_DATABRICKS_EXPERIMENT_NAME	Databricks runtime experiment.
FLEET_MLFLOW_DATABRICKS_EVAL_EXPERIMENT_NAME	Databricks evaluation experiment.
FLEET_MLFLOW_DATABRICKS_OPTIMIZATION_EXPERIMENT_NAME	Databricks GEPA experiment.
FLEET_MLFLOW_DATABRICKS_TRACE_CATALOG	Unity Catalog trace catalog.
FLEET_MLFLOW_DATABRICKS_TRACE_SCHEMA	Runtime and evaluation trace schema.
FLEET_MLFLOW_DATABRICKS_TRACE_TABLE_PREFIX	Runtime trace table prefix.
FLEET_MLFLOW_DATABRICKS_TRACING_SQL_WAREHOUSE_ID	SQL warehouse for trace export.
FLEET_MLFLOW_DATABRICKS_OPTIMIZATION_TRACE_SCHEMA	Optimization trace schema.
FLEET_MLFLOW_DATABRICKS_OPTIMIZATION_TRACE_TABLE_PREFIX	Optimization trace table prefix.
FLEET_MLFLOW_DATABRICKS_EVAL_TRACE_TABLE_PREFIX	Evaluation trace table prefix.
FLEET_HOST	Server bind address. HOST is also accepted.
FLEET_PORT	Server port. PORT is also accepted.
FLEET_ALLOW_NON_LOOPBACK_BIND	Permit a non-loopback bind. ALLOW_NON_LOOPBACK_BIND is also accepted.

Credentials that are read but are not FLEET_*-prefixed are DATABRICKS_HOST, DATABRICKS_TOKEN, and TYPESAFE_API_KEY. The first two are the gateway and Databricks SDK identity; DATABRICKS_TOKEN is stored as a SecretStr.

Several unprefixed aliases (HOST, PORT, MAX_UPLOAD_BYTES, MAX_ACTIVE_SESSIONS, MAX_LLM_CALLS_PER_TURN, COMPILED_PROGRAM_DIR, LOCAL_SKILLS_DIR, DAYTONA_AUTO_STOP_MINUTES, ALLOW_NON_LOOPBACK_BIND) exist for deployment compatibility. Prefer the FLEET_ forms.

Retired MLflow names

The loader rejects these names when they appear in the process environment (for FLEET_*) or in .env (for all of them):

FLEET_MLFLOW_MODE
MLFLOW_TRACKING_URI
MLFLOW_EXPERIMENT_NAME
FLEET_MLFLOW_TRACKING_URI
FLEET_MLFLOW_EXPERIMENT_NAME
FLEET_MLFLOW_EVAL_EXPERIMENT_NAME
FLEET_MLFLOW_OPTIMIZATION_EXPERIMENT_NAME
FLEET_MLFLOW_TRACE_CATALOG
FLEET_MLFLOW_TRACE_SCHEMA
FLEET_MLFLOW_TRACE_TABLE_PREFIX
FLEET_MLFLOW_TRACING_SQL_WAREHOUSE_ID
FLEET_MLFLOW_OPTIMIZATION_TRACE_SCHEMA
FLEET_MLFLOW_OPTIMIZATION_TRACE_TABLE_PREFIX
FLEET_MLFLOW_EVAL_TRACE_TABLE_PREFIX

The error tells the operator to migrate to FLEET_MLFLOW_LOCAL_* or FLEET_MLFLOW_DATABRICKS_* and to select the backend with --mlflow local|databricks. Conflicting selectors, such as fleet cli databricks --mlflow local, are argument errors.

Provenance, digest, and /config

FleetSettings.configuration() builds the reporting payload:

Key	Content
schema_version	Always 4.
digest	SHA-256 over the sorted, compact JSON encoding of the non-secret values.
values	Every non-secret field in JSON mode. Secret fields are excluded entirely.
sources	One of default, toml, dotenv, environment, explicit, or session per field.
mlflow_target	Mode, tracking URI, and the three experiment names for the selected backend.
file_changes_require_restart	Always true.

The terminal /config command calls GET /sessions/{session_id}/config, which returns the session's mode, models, dataset context, limits, and this configuration object. /config json prints the raw payload. /settings is an alias. The panel shows the first 16 characters of the digest and lists up to eight fields whose source is not default.

The digest covers both MLflow profiles even though only one is active, because all profile fields participate in values. GEPA approval evidence records configuration identity; changing any included value invalidates evidence created under a different digest.

Persisted session overrides

Mode and root/sub model selections made in the terminal are persisted per Session. They are applied at Turn boundaries and reported with source session in /config. They do not rewrite the TOML file or process settings. Operator-owned values such as judge model, credentials, deployment policy, and resource ceilings are not session-editable.

with_explicit_overrides validates a small set of CLI overrides (host, port, mlflow_local_port, and the selected runtime experiment name) against the current settings, preserves provenance for unchanged fields, and rejects unknown field names.

Validation behavior

Startup fails before serving if any of these checks fail:

• Required strings (fleet_database_url, fleet_daytona_snapshot, and the three model routes) are non-empty after stripping.
• Model routes begin with openai/ and have a non-empty service identifier.
• FLEET_LLM_BASE_URL is empty or an HTTPS URL with a network location.
• Public URLs contain no username, password, query string, or fragment.
• The shared notes subpath is relative and free of .., //, and a trailing slash.
• The database schema matches [a-z_][a-z0-9_]{0,62}.
• The judge model is a <provider>:/<model> URI.
• A migration DSN points at the runtime database.
• A Lakebase endpoint matches projects/<id>/branches/<id>/endpoints/<id> and both DSNs meet the TLS and credential rules.
• Databricks mode has a databricks URI, all trace storage settings, and absolute experiment paths.

get_settings(mlflow_mode) caches one FleetSettings per process (lru_cache(maxsize=1)), so a backend choice made at launch applies for the lifetime of the process.

Related

• CLI reference for command-line overrides and --mlflow selection.
• Deployment for environment and secret placement.
• Security for credential handling and bind restrictions.
• Getting started for a first local run.
• Evaluation and metrics for how configuration identity gates approval.