Configuration

Overview#

The uf CLI uses a unified configuration system. All settings live in .uf/config.yaml at the repository root. The file is optional — when absent, compiled defaults apply with no error. You never need to create this file manually; uf config init generates it with all values commented out so you can see what’s available and uncomment what you want to change.

Commands#

config init#

Create or update .uf/config.yaml. Generates a fully-commented template showing all available settings with their defaults. Existing files are updated with new sections while preserving your customizations.

uf config init              # current directory
uf config init --dir ./myproject

config show#

Display the effective configuration after all layers merge. Shows the final resolved values — useful for debugging which layer a setting came from.

uf config show              # human-readable text
uf config show --format json  # machine-parseable JSON

config validate#

Validate the config file against known field values. Reports invalid keys, unknown sections, and type mismatches.

uf config validate
uf config validate --format json

Layered Loading#

Configuration is resolved through 5 layers. Each layer overrides the one below it:

CLI flags           ← highest priority (always wins)
Environment vars    ← override config files
Repo config         ← .uf/config.yaml in the project
User config         ← ~/.config/uf/config.yaml (per-user defaults)
Compiled defaults   ← lowest priority (built into the binary)

Repo config (.uf/config.yaml) is for project-specific settings shared across the team via version control. User config (~/.config/uf/config.yaml) is for personal defaults that apply across all projects — like your preferred package manager or a custom embedding host.

Missing config files are not an error. If neither file exists, compiled defaults apply for all settings.

Environment Variable Overrides#

Every config field can be overridden with an environment variable. The naming convention is UF_ + section + _ + field in uppercase:

Precedence Example#

If your user config sets gateway.port: 8080 and your repo config sets gateway.port: 9090, the repo config wins (it’s higher priority). If you then run uf gateway --port 3000, the CLI flag wins over both.

Configuration Sections#

The config file has 7 sections. Each controls a specific part of the uf toolchain:

Common Customizations#

Set the package manager (Fedora/RHEL)#

setup:
  package_manager: dnf

By default, uf setup auto-detects your package manager (Homebrew on macOS, apt on Debian/Ubuntu). Override this for platforms where auto-detection picks the wrong one.

Change the embedding model#

embedding:
  model: nomic-embed-text
  dimensions: 768

The default model (granite-embedding:30m) is optimized for low-resource machines. If you have more VRAM or need higher-quality embeddings, switch to a larger model and update dimensions to match.

Change the gateway port#

gateway:
  port: 9090

The default port (53147) avoids conflicts with common services. Change it if you have a port conflict or prefer a standard port.

Open an IDE with sandbox sessions#

sandbox:
  ide: vscode

By default, uf sandbox start creates the workspace without opening an IDE (none). Set ide to have DevPod automatically open your preferred editor after workspace creation. Valid values: none, vscode, openvscode, fleet, jupyternotebook, cursor.

Skip tools during setup#

setup:
  skip:
    - gaze
    - mxf

Skip tools you don’t need. This speeds up uf setup and avoids installing dependencies for tools you won’t use.

See Also#

• Common Workflows – Workflow configuration with .uf/config.yaml
• Quick Start – Install and verify the toolchain
• Developer Guide – Daily workflow with the uf CLI