Home

Hypha

A dotfile and user-environment configuration manager, built around a resource graph and pluggable controllers rather than a fixed set of "link this file here" rules.

The reconciliation model is closer to Kubernetes than a traditional dotfile manager, but designed to operate directly on a single machine.

You declare what should exist:

• Packages
• Symlinks
• Directories
• Cloned Repositories
• Extracted Archives
• Templated Files
• and other system resources

Using manifests written in:

• JSON
• YAML
• or Jsonnet

You can optionally use Lua for scripting, resource decoration and extensions.

Then, Hypha builds a resource graph and reconciles it against the current system state.

Each resource kind has a controller responsible for:

1. Observing the current state
2. Plan the required changes
3. Applying the changes to the system

For example:

1. Declare a manifest for a Package resource:

kind: Package
metadata:
  name: git
  labels:
  - dev
spec:
  name: git # install git using the default package manager.

2. Optionally, preview the changes:

Highly recommended that you run hypha plan before hypha apply so you can preview the changes to your system.

hypha plan  # show the changes that would be made

3. Apply the changes to your system:

hypha apply # apply the changes to the system

Where to Go?

• New here → Getting Started
• Using the CLI day to day → User Guide
• Declaring resources of a specific kind → Built-in Resources (sidebar)
• Coming from another tool → Migrating (sidebar)
• Writing a controller, or understanding how the reconciler works internally → Developer Guide (sidebar), Architecture
• Something not doing what you expected → Troubleshooting

Status

Hypha is under active development, and this wiki says so plainly where it matters rather than describing aspirational behavior as current.

Look for status markers:

Marker	Description
🟢	working
🟡	built but not wired up yet
🔴	planned or stub

The short version:

• 🟢 The resource graph
• 🟢 dependency scheduling
• 🟢 manifest parsing
• 🟢 schema validation
• 🟢 query engine

Most individual controllers --- the components that actually create and manage the system resources --- are not yet wired up to modify the system.