Skip to content

Home

Jump to bottom
Aleem Isiaka edited this page Mar 31, 2026 · 5 revisions

Welcome to Heimdal

A universal dotfile and system configuration manager

Heimdal automatically manages your dotfiles, installs packages, and keeps your development environment in sync across multiple machines.

Quick Links

What is Heimdal?

Heimdal is a cross-platform tool that helps you:

  • Manage dotfiles across multiple machines with intelligent symlinking
  • Install packages from a unified interface (Homebrew, APT, DNF, Pacman, APK, MAS)
  • Keep configurations in sync using Git
  • Use multiple profiles for different machines (work, personal, server)
  • Store secrets securely using OS-native keychains
  • Import from existing tools like GNU Stow, dotbot, chezmoi, yadm, homesick

Key Features

Universal Package Management

Packages are defined in heimdal.yaml under each profile's packages: section. Use common: for cross-platform packages, or specify packages per manager (homebrew:, apt:, dnf:, etc.).

Learn more

Intelligent Symlinking

  • GNU Stow-style fallback when dotfiles: list is empty
  • Automatic conflict detection
  • --force and --backup options
  • Rollback support

Learn more

Profile System

  • Multiple profiles (work, personal, server)
  • Profile inheritance via extends:
  • Packages/dotfiles/templates/ignore are unioned; hooks are replaced
  • Easy switching with heimdal profile switch

Learn more

Template System

  • {{ variable }} substitution syntax
  • Undefined variables are preserved (not errors)
  • System variables: os, hostname, user, home, env.VAR, secrets.NAME
  • Per-profile vars: in the templates list

Learn more

Secret Management

  • OS-native keychain via keyring (macOS Keychain, Linux Secret Service)
  • Secrets never stored in Git
  • Names-only manifest at <dotfiles_path>/.heimdal/secrets_manifest.json
  • Available in templates as {{ secrets.NAME }}

Learn more

Git-Based Sync

  • heimdal sync pulls from remote and applies config
  • heimdal commit stages and commits with optional push
  • heimdal autosync for background automation
  • All Git operations shell out to the git binary

Learn more

Getting Started

1. Install Heimdal

macOS (Homebrew)

brew install limistah/tap/heimdal

Any Platform (Cargo)

cargo install heimdal

See all installation methods

2. Run the Wizard

heimdal wizard

The wizard offers three flows:

  • Fresh setup — scan your system and generate a config
  • Import existing — migrate from Stow, dotbot, chezmoi, yadm, or homesick
  • Clone existing repo — set up Heimdal on a new machine from your existing dotfiles repo

Complete setup guide

3. Apply Configuration

heimdal apply

This installs packages, creates symlinks, and renders templates.

Documentation

Community & Support

Quick Examples

Add a Package

heimdal packages add neovim --manager homebrew

Switch Profiles

heimdal profile switch work
heimdal apply

Sync Configuration

heimdal sync

Store a Secret

heimdal secret add API_KEY --value "your-secret-value"

Ready to get started? Quick Start Guide

Need help? Troubleshooting

Getting Started

User Guides

CLI Reference

Help

Contributing

Main Repository

Clone this wiki locally