Configuration & Policy

Complete Configuration Guide for OMG

This guide covers all configuration options, file locations, security policies, and customization options for OMG.

📍 File Locations

OMG follows the XDG Base Directory Specification with sensible fallbacks.

Configuration Files

File	Purpose	Default Path
config.toml	General settings	`~/.config/omg/config.toml`
policy.toml	Security policy	`~/.config/omg/policy.toml`

Data Directory

Directory	Purpose	Default Path
Data root	All OMG data	`~/.local/share/omg/`
Versions	Runtime installations	`~/.local/share/omg/versions/`
Tools	Installed CLI tools	`~/.local/share/omg/tools/`
Mise	Bundled mise binary	`~/.local/share/omg/mise/`
Cache	Persistent cache (redb)	`~/.local/share/omg/cache.redb`
History	Transaction history	`~/.local/share/omg/history.json`
Audit	Audit log	`~/.local/share/omg/audit/audit.jsonl`

⚙️ General Configuration (config.toml)

The main configuration file controls daemon behavior, runtime settings, and feature toggles.

Complete Example

# ~/.config/omg/config.toml

# ═══════════════════════════════════════════════════════════════════════════
# GENERAL SETTINGS
# ═══════════════════════════════════════════════════════════════════════════

# Enable shim system for IDE compatibility (default: false)
# Shims are slower than PATH modification but work with all IDEs
shims_enabled = false

# Override data directory (default: ~/.local/share/omg)
# data_dir = "/custom/path/omg"

# Override socket path (default: $XDG_RUNTIME_DIR/omg.sock)
# socket_path = "/run/user/1000/omg.sock"

# Default shell for hooks and completions
# Options: "zsh", "bash", "fish"
default_shell = "zsh"

# Automatically check for runtime updates on install (default: false)
auto_update = false

# Runtime backend preference
# Options: "native", "mise", "native-then-mise" (default)
runtime_backend = "native-then-mise"

# ═══════════════════════════════════════════════════════════════════════════
# AUR BUILD SETTINGS
# ═══════════════════════════════════════════════════════════════════════════

[aur]
# Build method: "bubblewrap" (secure), "chroot", or "native" (default)
build_method = "native"

# Number of parallel AUR builds
build_concurrency = 8

# Require interactive PKGBUILD review before building (default: false)
review_pkgbuild = false

# Use stricter makepkg flags (cleanbuild/verifysource) (default: true)
secure_makepkg = true

# Allow native builds without sandboxing (default: true)
allow_unsafe_builds = true

# Use AUR metadata archive for bulk update checks (default: true)
use_metadata_archive = true

# Metadata archive cache TTL in seconds (default: 300)
metadata_cache_ttl_secs = 300

# MAKEFLAGS for building (passed to makepkg)
# makeflags = "-j8"

# Custom package destination (built packages stored here)
# pkgdest = "/home/user/.cache/omg/pkgdest"

# Custom source destination (sources downloaded here)
# srcdest = "/home/user/.cache/omg/srcdest"

# Cache built packages for faster rebuilds (default: true)
cache_builds = true

# Enable ccache for faster C/C++ builds (default: false)
enable_ccache = false
# ccache_dir = "/home/user/.cache/ccache"

# Enable sccache for faster Rust builds (default: false)
enable_sccache = false
# sccache_dir = "/home/user/.cache/sccache"

Setting Descriptions

General Settings

Setting	Type	Default	Description
`shims_enabled`	bool	`false`	Use shims instead of PATH modification
`data_dir`	string	`~/.local/share/omg`	Override data directory
`socket_path`	string	XDG runtime	Override socket path
`default_shell`	string	`"zsh"`	Default shell for hooks
`auto_update`	bool	`false`	Auto-check for updates
`runtime_backend`	string	`"native-then-mise"`	Runtime resolution strategy

AUR Settings

Setting	Type	Default	Description
`build_method`	string	`"native"`	Build isolation method (`bubblewrap`, `chroot`, `native`)
`build_concurrency`	int	CPU count	Parallel AUR builds
`review_pkgbuild`	bool	`false`	Require manual PKGBUILD review
`secure_makepkg`	bool	`true`	Use cleanbuild/verifysource
`use_metadata_archive`	bool	`true`	Use bulk metadata for fast updates
`cache_builds`	bool	`true`	Cache built packages
`enable_ccache`	bool	`false`	Use ccache for C/C++
`enable_sccache`	bool	`false`	Use sccache for Rust

🛡️ Security Policy (policy.toml)

The security policy controls what packages can be installed and their required security grades.

Complete Example

# ~/.config/omg/policy.toml

# ═══════════════════════════════════════════════════════════════════════════
# SECURITY POLICY CONFIGURATION
# ═══════════════════════════════════════════════════════════════════════════

# Minimum required security grade for package installation
# Options: "Risk", "Community", "Verified", "Locked"
# 
# Grade hierarchy (lowest to highest):
#   Risk      - Known vulnerabilities present
#   Community - AUR/unsigned packages
#   Verified  - PGP/checksum verified (official repos)
#   Locked    - SLSA Level 3 + PGP verified (core packages)
minimum_grade = "Verified"

# Allow installation of AUR packages
# Set to false to restrict to official repos only
allow_aur = true

# Require PGP signature verification for all packages
# When true, unsigned packages will be rejected
require_pgp = false

# Allowed software licenses (SPDX identifiers)
# Leave empty to allow all licenses
# When populated, only packages with these licenses can be installed
allowed_licenses = [
    "AGPL-3.0-or-later",
    "Apache-2.0",
    "MIT",
    "BSD-2-Clause",
    "BSD-3-Clause",
    "GPL-2.0-or-later",
    "GPL-3.0-or-later",
    "LGPL-2.1-or-later",
    "LGPL-3.0-or-later",
    "MPL-2.0",
    "ISC",
    "Unlicense",
    "CC0-1.0",
]

# Explicitly banned packages (will never be installed)
# Useful for blocking packages with known issues
banned_packages = [
    # "example-malicious-package",
    # "deprecated-insecure-tool",
]

# ═══════════════════════════════════════════════════════════════════════════
# ADVANCED POLICY OPTIONS
# ═══════════════════════════════════════════════════════════════════════════

# Block packages with known CVEs above this severity (0.0-10.0)
# max_cve_severity = 7.0

# Require SBOM for installed packages
# require_sbom = false

# Enable SLSA provenance verification
# verify_slsa = true

# Trusted packagers/maintainers
# trusted_maintainers = ["username1", "username2"]

Security Grades Explained

Grade	Level	Description	Examples
Locked	3	SLSA Level 3 + PGP verified	`glibc`, `linux`, `pacman`
Verified	2	PGP/checksum verified	Official repo packages
Community	1	AUR/unsigned sources	AUR packages
Risk	0	Known vulnerabilities	CVE-affected packages

Policy Enforcement

When you run omg install:

Package grading: Each package is assigned a security grade
Policy check: Grade compared against minimum_grade
AUR check: If AUR package and allow_aur = false, rejected
PGP check: If require_pgp = true and no signature, rejected
License check: If allowed_licenses is set and license not in list, rejected
Ban check: If package in banned_packages, rejected

Example Policies

Permissive (Default)

minimum_grade = "Community"
allow_aur = true
require_pgp = false
allowed_licenses = []
banned_packages = []

Corporate/Secure

minimum_grade = "Verified"
allow_aur = false
require_pgp = true
allowed_licenses = ["Apache-2.0", "MIT", "BSD-3-Clause"]
banned_packages = ["known-bad-pkg"]

Paranoid/Air-gapped

minimum_grade = "Locked"
allow_aur = false
require_pgp = true
allowed_licenses = ["AGPL-3.0-or-later"]
banned_packages = []

🔄 Runtime Backend Configuration

OMG supports three runtime backends:

native

Uses OMG's built-in pure Rust runtime managers.

runtime_backend = "native"

Supported runtimes: Node, Python, Go, Rust, Ruby, Java, Bun

mise

Uses the bundled mise tool for all runtimes.

runtime_backend = "mise"

Supported runtimes: 100+ runtimes

native-then-mise (Default)

Prefers native managers, falls back to mise for unsupported runtimes.

runtime_backend = "native-then-mise"

Best of both worlds: Fast native managers + wide mise compatibility

📁 Version File Support

OMG automatically detects version files in your project:

File	Runtime	Format
`.nvmrc`	Node.js	`20.10.0` or `lts/*`
`.node-version`	Node.js	`20.10.0`
`.bun-version`	Bun	`1.0.25`
`.python-version`	Python	`3.12.0`
`.ruby-version`	Ruby	`3.3.0`
`.go-version`	Go	`1.21.0`
`.java-version`	Java	`21`
`rust-toolchain.toml`	Rust	TOML format (see below)
`.tool-versions`	Multi	asdf format
`.mise.toml`	Multi	Mise format
`.mise.local.toml`	Multi	Local overrides
`mise.toml`	Multi	Project root
`package.json`	Node/Bun	`engines` or `volta` field
`go.mod`	Go	`go 1.21` directive

rust-toolchain.toml Format

[toolchain]
channel = "stable"  # or "nightly", "1.75.0"
components = ["rustfmt", "clippy"]
targets = ["x86_64-unknown-linux-gnu"]
profile = "minimal"  # or "default", "complete"

.tool-versions Format

node 20.10.0
python 3.12.0
rust stable
go 1.21.0

.mise.toml Format

[tools]
node = "20.10.0"
python = "3.12.0"
rust = "stable"
deno = "1.40.0"

🌐 Environment Variables

OMG respects these environment variables:

Variable	Purpose	Default
`OMG_SOCKET_PATH`	Override socket path	XDG runtime
`OMG_DATA_DIR`	Override data directory	`~/.local/share/omg`
`OMG_CONFIG_DIR`	Override config directory	`~/.config/omg`
`OMG_LOG_LEVEL`	Logging level	`info`
`GITHUB_TOKEN`	For `omg env share`	-
`XDG_RUNTIME_DIR`	XDG runtime directory	`/run/user/$UID`
`XDG_DATA_HOME`	XDG data directory	`~/.local/share`
`XDG_CONFIG_HOME`	XDG config directory	`~/.config`

🔧 Advanced Configuration

Systemd Service

Create a systemd user service for the daemon:

# ~/.config/systemd/user/omgd.service

[Unit]
Description=OMG Package Manager Daemon
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/omgd --foreground
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable omgd
systemctl --user start omgd

Shell Hook Customization

The shell hook adds these functions to Zsh:

Function	Description
`omg-ec`	Explicit package count (cached)
`omg-tc`	Total package count (cached)
`omg-oc`	Orphan count (cached)
`omg-uc`	Updates count (cached)
`omg-explicit-count`	Fresh explicit count
`omg-total-count`	Fresh total count
`omg-orphan-count`	Fresh orphan count
`omg-updates-count`	Fresh updates count

Use in your prompt:

# In .zshrc PROMPT
PROMPT='$(omg-ec) pkgs %~$ '

Custom Mirrors (Future)

# In config.toml (planned)
[mirrors]
arch = "https://custom-mirror.example.com/archlinux"
aur = "https://aur.archlinux.org"

📋 Configuration Examples

Minimal Configuration

# ~/.config/omg/config.toml
# Empty file uses all defaults

Developer Workstation

# ~/.config/omg/config.toml
default_shell = "zsh"
runtime_backend = "native-then-mise"

[aur]
build_concurrency = 16
enable_ccache = true
cache_builds = true

CI/CD Server

# ~/.config/omg/config.toml
auto_update = false
runtime_backend = "native"

[daemon]
refresh_interval = 60
cache_ttl = 60

[aur]
build_concurrency = 4
cache_builds = false

Enterprise/Secure

# ~/.config/omg/config.toml
[daemon]
max_cache_entries = 5000
cache_ttl = 600

# ~/.config/omg/policy.toml
minimum_grade = "Verified"
allow_aur = false
require_pgp = true
allowed_licenses = ["Apache-2.0", "MIT", "BSD-3-Clause"]
banned_packages = []

🔍 Troubleshooting Configuration

Verify Configuration

# Check config file syntax
omg doctor

# View effective configuration
omg status

Common Issues

Issue	Solution
Config not loading	Check file path and TOML syntax
Permission denied	Ensure socket/data dirs are writable
Policy blocking packages	Lower `minimum_grade` or set `allow_aur = true`
Runtime not found	Check `runtime_backend` setting

Reset to Defaults

# Remove config files
rm ~/.config/omg/config.toml
rm ~/.config/omg/policy.toml

# OMG will use defaults
omg status

📚 See Also

Security & Compliance — Detailed security policy documentation
Daemon Internals — Advanced daemon configuration
Runtime Management — Version file formats

📍 File Locations​

Configuration Files​

Data Directory​

⚙️ General Configuration (config.toml)​

Complete Example​

Setting Descriptions​

General Settings​

AUR Settings​

🛡️ Security Policy (policy.toml)​

Complete Example​

Security Grades Explained​

Policy Enforcement​

Example Policies​

Permissive (Default)​

Corporate/Secure​

Paranoid/Air-gapped​

🔄 Runtime Backend Configuration​

native​

mise​

native-then-mise (Default)​

📁 Version File Support​

rust-toolchain.toml Format​

.tool-versions Format​

.mise.toml Format​

🌐 Environment Variables​

🔧 Advanced Configuration​

Systemd Service​

Shell Hook Customization​

Custom Mirrors (Future)​

📋 Configuration Examples​

Minimal Configuration​

Developer Workstation​

CI/CD Server​

Enterprise/Secure​

🔍 Troubleshooting Configuration​

Verify Configuration​

Common Issues​

Reset to Defaults​

📚 See Also​

📍 File Locations

Configuration Files

Data Directory

⚙️ General Configuration (config.toml)

Complete Example

Setting Descriptions

General Settings

AUR Settings

🛡️ Security Policy (policy.toml)

Complete Example

Security Grades Explained

Policy Enforcement

Example Policies

Permissive (Default)

Corporate/Secure

Paranoid/Air-gapped

🔄 Runtime Backend Configuration

native

mise

native-then-mise (Default)

📁 Version File Support

rust-toolchain.toml Format

.tool-versions Format

.mise.toml Format

🌐 Environment Variables

🔧 Advanced Configuration

Systemd Service

Shell Hook Customization

Custom Mirrors (Future)

📋 Configuration Examples

Minimal Configuration

Developer Workstation

CI/CD Server

Enterprise/Secure

🔍 Troubleshooting Configuration

Verify Configuration

Common Issues

Reset to Defaults

📚 See Also