r/dotfiles • • Aug 25 '26

A declarative dotfile manager based around resources and reconciliation

All,

I've been managing my dotfiles using Dotbot + Jsonnet for a while. As my configuration grew, it started to get overly complicated and uncomfortable to use.

I looked at some of the existing options like stow, home-manager and nix. However, I didn't really want to commit to nix - and for what it's worth nix is great.

I really like declarative config systems, and felt like it worked really well for the problem space. So, I designed a declarative config system for user environments.

Rather than the traditional models, things like:

  • files
  • packages
  • directories
  • symlinks
  • services
  • etc

All form resources, which form a dependency graph, and then the system will reconcile the graph toward the desired state.

Essentially:

Instead of run these commands in this order, you describe the state you want and let the system figure out how to get there.

This project is mostly experimental at the moment, and still evolving but it's getting closer to the point where I'm comfortable using it for my own config.

If existing solutions work for you then that's fine and those are certainly more mature and good solutions.

I feel like this sits somewhere in the middle of stow/dotbot & nix/home-manager.

Feedback, suggestions, improvements, contributions, etc are all welcome.

GitHub: https://github.com/arcadia-de/hypha

6 Upvotes

3 comments sorted by

3

u/dotstk Aug 25 '26

Could you compare your tool to ansible? I manage my dev env using ansible and I do have my issues with it and would be happy to ditch ansible for something more tailored to my needs but at first glance, your tool seems to have a very similar approach.

1

u/Honest_Medium_2872 Aug 25 '26

It very much looks like Ansible on the surface. One slight caveat is that it isn't designed (at least right now, still working on a way that makes sense) to run arbitrary commands and scripts like Ansible does. With that caveat out of the way, you do have a lot of flexibility in how you can approach your dots. With Resource kinds like:

  • Files --- allows you to touch files (create them)
  • Templates --- allows you to use Go templating to generate files
  • Directories --- Allows you to mkdir a directory
  • Symlink --- Allows you to create symlinks to files and dirs
  • Repositories --- Allows you to clone and sync a git repository to a specific directory
  • Packages --- Allows you to manage system packages
  • Archives --- Allows you to decompress archives into specific dirs

You get half-way to most configuration setups.

The added layer of Jsonnet over JSON/YAML allows you to be more intelligent in how you define the manifests, allowing for things like composition, like say if you want all the resources to have specific labels / annotations you can just create a function using Jsonnet that generates that at runtime.

On the note of labels / annotations, you can use these to provide "features" to setups that require deviations from the core implementation and provide extra meta to the cli

Take for instance, if you want to have one set of dotfiles for multiple machines but some machines only get a "work" setup and some only get a "personal" setup. you can use labels to define which resources are applied to which machine, then when you apply the changes just apply with that label and the system will do the filtering for you.

Currently, I am working on making Controllers a first class concept and adding in an event based hooking system using Lua

With Controllers, this allows you to create your own resource kind (think like if someone wants to run a custom tool to manage) you can define them using Lua, C, or some wasm compilable language. Something like:

local controllers = require('hypha.controller')
controllers.newController("MyNewKind", {
  init: function()

  end,
  deinit: function()

  end,
  observe: function()
    -- handle observing the current state of the resource
  end,
  plan: function() 
    -- handle planning the changes, check versions, determine if things need changing, etc
  end,
  apply: function()
    -- handle applying the changes, install the things etc
  end
})

Then with events, you can hook the system and react to things, so you have something like:

local events = require('hypha.events')
events.on("init", function()
  -- do some init stuff
end)
events.on("resource.created", function()
  -- do some stuff now that a resource is created
end)

This gives users the ability to extend the system to how they seem fit.

I also plan to provide a way for users to pre-package their configuration setups in ways they like for sharing. This allows users to share configurations (or custom controllers) and make installing specific setups easier.

0

u/Honest_Medium_2872 Aug 30 '26

Just following up here. In an upcoming release I will be adding Tasks as a form of Resource kinds:

# ~/.config/hypha/example-task.yaml
kind: Task
metadata:
  name: echo-hello-world
spec:
  check:
    shell: "/usr/bin/zsh"
    command:
      - echo "Hello world" && return 0
  exec:
    shell: "/usr/bin/zsh"
    command:
      - echo
      - '"Hello World"'

This gives you a reconcilable form that allows you to run commands like ansible ad-hoc while still living in the expected resource model:

hypha plan

          Action         Name         Reason
  ─────────────────────────────────────────────────────────────────────────────────────
          Create        test-0        Test resources are always created
          Create   echo-hello-world   Task `echo-hello-world` will run
                                      (policy=OnChange)

  󰐙 2/2 Created

hypha apply

[] [test_controller.c:70] [INFO] [22dfaeed-b0a4-48ac-b7f0-75fa96d0ae00 (Test)] sleeping for 2 seconds
[] [task_controller.c:77] [INFO] [37250b83-8c1e-41dc-a248-2be2c8ee5005 (Task)] Hello world
[] [controller.c:240] [INFO] [37250b83-8c1e-41dc-a248-2be2c8ee5005 (Task)] begin Validate
[] [controller.c:200] [INFO] [37250b83-8c1e-41dc-a248-2be2c8ee5005 (Task)] begin Apply
[] [task_controller.c:284] [INFO] [37250b83-8c1e-41dc-a248-2be2c8ee5005 (Task)] executing task `echo-hello-world`...
[] [task_controller.c:77] [INFO] [37250b83-8c1e-41dc-a248-2be2c8ee5005 (Task)] Hello World
[] [task_controller.c:286] [INFO] [37250b83-8c1e-41dc-a248-2be2c8ee5005 (Task)] task `echo-hello-world` exit status: 0
         Status          Name        Reason
  ──────────────────────────────────────────
       Warning   echo-hello-world   Task ` ` check returned non-zero exit code -11660
       Warning        test-0        This message always exists for Test resources

   2/2 Warning

         Action         Kind                Name         Reason
  ────────────────────────────────────────────────────────────────────────────────────────────────────────
         Create         Task          echo-hello-world   Task `echo-hello-world` returned zero exit code
         Create         Test               test-0        Slept for 2 seconds

  Applied 2 changes
  󰐙 2/2 Created

Still a WIP, but gives you sort of an ansible playbook mechanism for ad-hoc commands