Configuration Tutorial

Prerequisites#

The uf CLI must be installed. Run uf version to confirm.

Step 1: Create a Config File#

Generate a config file with all available settings commented out:

uf config init

This creates .uf/config.yaml in your project directory. The file contains every configuration key as a YAML comment with its default value. Nothing is active until you uncomment it.

Created .uf/config.yaml (all values commented — defaults apply)

Open the file to see the available sections:

# setup:
#   package_manager: auto    # auto, brew, dnf, apt
#   skip: []                 # tools to skip during setup

# scaffold:
#   language: ""             # auto-detected from go.mod, pyproject.toml, package.json, etc.

# embedding:
#   model: granite-embedding:30m
#   dimensions: 256

# sandbox:
#   runtime: auto            # auto, podman, docker
#   image: ""                # default: quay.io/unbound-force/opencode-dev:latest
#   ide: none                # none, vscode, openvscode, fleet, jupyternotebook, cursor

# gateway:
#   port: 53147
#   provider: ""             # auto, anthropic, vertex, bedrock

# doctor:
#   skip: []                 # checks to skip

# workflow:
#   execution_modes:
#     define: human           # human or swarm

Each key shows its default. Uncomment and change only what you need.

Step 2: Customize for Your Platform#

Scenario: Fedora/RHEL Package Manager#

By default, uf setup auto-detects your package manager (Homebrew on macOS, apt on Debian/Ubuntu, dnf on Fedora/RHEL). On Fedora or RHEL, you can set it explicitly to ensure dnf is always used:

setup:
  package_manager: dnf

With dnf set, uf setup installs tools like Podman via dnf install instead of Homebrew. Tools without dnf packages (Ollama, DevPod) fall back to their official curl installers with an interactive confirmation prompt. See the CLI reference for the full install cascade.

Verify the setting took effect:

uf config show

setup:
  package_manager: dnf    ← your override
  skip: []

The output shows the effective value after all config layers merge. Your override is active.

Scenario: Different Embedding Model#

The default embedding model (granite-embedding:30m) is optimized for low-resource machines. If you have more VRAM or need higher-quality embeddings:

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

The dimensions value must match what the model produces. Check the model’s documentation for the correct dimension count.

Scenario: Custom Gateway Port#

The default gateway port (53147) avoids conflicts with common services. If you have a conflict:

gateway:
  port: 9090

Scenario: Skip Tools During Setup#

Skip tools you do not need. This speeds up uf setup and avoids installing dependencies you will not use:

setup:
  skip:
    - gaze
    - mxf

After setting this, uf setup will install OpenCode, Speckit, Replicator, and Dewey but skip Gaze and Mx F.

Scenario: Default IDE for Sandbox Workspaces#

When using DevPod persistent workspaces, set a default IDE so it opens automatically after workspace creation:

sandbox:
  ide: vscode

Verify with uf config show:

uf config show

sandbox:
  ide: vscode    ← your override (default: none)

Now uf sandbox create will open VS Code after the workspace is ready. Valid values: none, vscode, openvscode, fleet, jupyternotebook, cursor. You can override per-command with uf sandbox create --ide cursor.

Step 3: Understand Config Precedence#

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

CLI flags           ← highest priority (always wins)
Environment vars
Repo config         ← .uf/config.yaml (project-specific, shared via git)
User config         ← ~/.config/uf/config.yaml (personal defaults)
Compiled defaults   ← lowest priority

Precedence Example#

Suppose your user config (~/.config/uf/config.yaml) sets a default gateway port:

gateway:
  port: 8080

And your repo config (.uf/config.yaml) sets a project-specific port:

gateway:
  port: 9090

The repo config wins (higher priority). Verify with uf config show:

uf config show

gateway:
  port: 9090    ← repo config wins over user config

If you then run uf gateway --port 3000, the CLI flag wins over both config files.

Step 4: Validate Your Config#

Catch errors before they surface at runtime:

uf config validate

If the config is valid:

✓ Config is valid

If there are problems (unknown keys, type mismatches):

✗ Config validation failed:
  - unknown key: setup.package_manger (did you mean package_manager?)
  - invalid value for gateway.port: "nine thousand" (expected integer)

Fix the issues and re-run uf config validate until it passes.

Step 5: View the Merged Config#

See the final effective configuration after all layers merge:

uf config show

This shows every key with its resolved value — useful for debugging which layer a setting came from. For machine-parseable output:

uf config show --format json

Summary#

See Also#

• Configuration Reference – All config sections, fields, and environment variable overrides
• Common Workflows – Workflow configuration with .uf/config.yaml
• Quick Start – Install and verify the toolchain
• Developer Guide – Daily workflow with the uf CLI