Guide to Athanor

Также доступно на русском.

This guide explains why Athanor exists and how it's built underneath — for whoever ends up using it daily, and for whoever goes digging through the code to change it. Either way, knowing "how to run it" isn't quite enough; "why it's built this way" is the more useful thing to carry around.

This isn't a flag reference — --help and the project's root README.md already cover that. This is the explanation of design.

How to read this

The chapters are meant to be read in order: each one builds on concepts from the last. If you already understand why age+sops exist and how the access model works, you can start from chapter 4 onward — but a first-time reader shouldn't skip ahead.

Each chapter ends with a checkpoint question. If you can't answer it without rereading the chapter, it's worth another pass before moving on.

1. The problem and the concept — why Athanor exists at all
2. Encryption: age and sops — the foundation everything else sits on
3. Manifest and access model — athanor.yaml and who can see what
4. CLI and Store — commands and where secrets live in memory
5. TUI — working with secrets interactively, by hand
6. MCP server — how secrets reach an agent
7. Deploy to a VPS — moving the whole setup to a server
8. End-to-end flows and diagnostics — how it all works together, and what to do when it doesn't

The core idea, in one paragraph

A secret should stay out of source code and direct tool responses unless you've explicitly allowed retrieval of that specific secret. Athanor stores secrets encrypted on disk (age+sops), decides who gets access to what (the athanor.yaml manifest), and offers three access channels with different levels of trust: CLI/TUI for a human at a terminal, run_with_secrets for passing a secret to a trusted command without direct retrieval, and get_secret — a deliberate, narrow escape hatch. The command can still print or transmit its environment; that boundary is explicit.

Source of truth

This guide explains design and reasoning; for the exact list of flags, current command behavior, and the source itself, always defer to:

• the project's README.md — a quick command reference;
• the source code in cmd/athanor/ and internal/ — the primary source; the guide can fall behind it after a refactor.

Snapshot at time of writing: Athanor v0.1.0, Go 1.26.6, sops 3.13.3, age 1.3.1.