Concepts

Understand the core abstractions that power DaemonHound.

Namespaces

A namespace is derived from the origin Git remote:

Shell

[email protected]:you/pingpong-api.git  →  github.com/you/pingpong-api

The same file can live at different physical paths on different machines:

Machine	Local path	Namespace
MacBook	`~/projects/pingpong-api/.env.local`	`github.com/you/pingpong-api`
Work PC	`~/work/pingpong-api/.env.local`	`github.com/you/pingpong-api`
Windows	`D:\code\pingpong-api\.env.local`	`github.com/you/pingpong-api`

Global namespace

Files outside a Git repo use the global namespace:

Shell

dhd track ~/.zshrc --mode backup
dhd track ~/.gitconfig

File modes

Mode	Behavior	Use case
`sync`	Shared across all machines	Project `.env` files
`backup`	Machine-specific, no cross-machine merge	Shell configs

Vault layout

Vault

vault/
├── sync/
│   └── github.com/you/pingpong-api/
│       ├── .env.local.age
│       └── .env.test.age
├── backup/
│   └── <machine-uuid>/
│       └── global/
│           └── zshrc.age
└── secrets/
    ├── openai-key.age
    └── github-token.age

Encryption

DaemonHound uses age for encryption. The vault only contains .age files.

The age identity key (~/.dh/identity.age) is:

Generated once at dhd init
Encrypted with your master password
Never stored in the vault
Never transmitted anywhere

If you lose this key, your data cannot be recovered. Back it up.

Machine identity

Each machine gets a stable UUID at dhd init. Hostnames are not used — they change across renames and MDM.

Architecture

DaemonHound
├── Namespace Resolver   → Derives namespace from git origin
├── File Tracker         → Maps namespace + path + mode
├── Secret Store         → Encrypted key-value with file refs
├── Encryption Layer     → age (filippo.io/age)
├── Sync Engine          → Diff, encrypt, push/pull, restore
└── Git Backend          → Your own private Git repository

Non-goals

DaemonHound is not:

An enterprise secret management platform
A team collaboration / RBAC tool
A secret leasing or rotation policy engine
A Kubernetes or cloud infrastructure tool

Commands Daemon