Project Configuration

OmegaFlow configuration controls the omegaflow tool itself: where recording files live, where generated run state is written, which action runs by default, and how the process loads its .env file. It is separate from recording configuration, which lives in the recording workspace and describes individual videos.

The bundled OmegaFlow base config is used by default. omegaflow bootstrap=project creates a project-local tool config so the recording workspace is explicit for everyone working in that project.

Override Order

OmegaFlow composes tool config in this order:

1. Schema default values.
2. The bundled base-config.yaml.
3. <project_root>/.omegaflow/config.yaml, when it exists.
4. CLI overrides such as omegaflow project_root=/path/to/project action=list.

The local file is optional, but bootstrap creates it.

.omegaflow/
  config.yaml

Project Config File

A project-owned OmegaFlow config should contain only the fields your project wants to override:

studio:
  recording_dir: recordings
  data_dir: recordings/.omegaflow

OmegaFlow looks for .omegaflow/config.yaml in the current project. The file is optional, and omegaflow bootstrap=project creates it for new projects.

Use the file for project defaults that should be shared by everyone working in the repository. Use CLI overrides for one-off changes:

omegaflow action=list studio.recording_dir=demos
omegaflow project_root=/path/to/project recording=hello
omegaflow recording=hello rec.capture.headless=false

OmegaFlow discovers project_root from the nearest .omegaflow/config.yaml or recordings/config.yaml in the current directory and its parents. An explicit Hydra override loads that project's .omegaflow/config.yaml, making it useful when invoking one project from another directory. Relative recording, data, output, and env-file paths are resolved from that root.

Common Fields

Field	Purpose
project_root	Automatically discovered project directory. Override it on the command line when operating on a different project.
studio.recording_dir	Directory containing config.yaml plus one directory per video. Each video directory contains index.md.
studio.data_dir	Directory for generated run state, scratch output, caches, and generated artifacts. Defaults to recordings/.omegaflow.
studio.keep_output_dir	Keeps Hydra's output directory metadata when a run is created.
studio.run_gc.enabled	Removes excess recording runs after a successful build and enables explicit action=gc. Defaults to true.
studio.run_gc.max_age_days	Retains successful, failed, and incomplete runs modified within this many days unless protected. Defaults to 30.
studio.run_gc.max_runs_per_recording	Bounds retained runs independently for each recording, subject to protected-run exceptions. Defaults to 10.
studio.run_gc.preserve_latest_failure	Protects the newest failed run for each recording. Defaults to true.
load_env_file	Enables the opt-in process-level env-file compatibility path before running actions. Defaults to false.
env_file	Optional process-level env file resolved from the project root. OmegaFlow TTS uses .omegaflow/omegaflow-secret.env instead.
env_override	Allows values from env_file to replace existing environment variables.
workspace	Bootstrap-only destination for bootstrap=project; defaults to studio.recording_dir.
watch_port	Optional fixed port for the local action=watch server. Leave unset to select a free port automatically.
autoplay	Controls countdown autoplay for action=watch. Set false to open the player paused.
beat	Optional top-level beat ID where action=watch starts playback. Nested pane beats are not watch targets.
dry_run	Preview without writing. For bootstrap, use dry_run=true to list generated files or dry_run=diff to show unified diffs.
rec	Recording config overrides merged on top of the selected recording. CLI shorthand such as rec.capture.headless=false is supported.
script_params	Values for parameters explicitly declared by the selected recording.

Recording defaults such as capture style, audio generation, publish surfaces, beats, setup, and cleanup belong in the recording workspace. See Recording Configuration.

For every CLI field and its action-specific meaning, see the Complete Option Reference.