tentaflake.dev★ Star on GitHub
[ 01 / 08 ] · AGENT ORCHESTRATION HOST

The declarative
Agent Host.

A NixOS flake template for running multiple isolated Hermes AI agents on one machine. Each agent gets its own Linux user, state directory, container, and key. Real OS-level isolation — declared in three lines of Nix.

11 NixOS modules · Go audit daemon · bootable installer ISO · MIT
macOS / Linux · headless / bare metal[ .NIX ]
clone>git clone https://github.com/timfewi/tentaflake
build iso>nix build .#installer-iso
deploy>sudo nixos-rebuild switch --flake .#agent-host
Read the docs →View on GitHub
[ BY THE NUMBERS ] · primitives compiled into one flake
01
∞
Agents per host
02
11
NixOS modules
03
0700
State dir perms
04
3
Lines per agent
[ 02 / 08 ] · MAIN FEATURES
// main features //

Everything in one flake.

Eight primitives that ship declared together — agents, secrets, containers, networking, TTS, audit, security, and a bootable installer.

01[ AGENTS ]

Any number, isolated

Run as many Hermes agents as you want on one machine — each in its own container with its own Linux user.

02[ AGENIX ]

Per-agent secrets

Encrypted .age files per agent, decrypted at build time. No cross-contamination, never in the Nix store. agenixFile > envFile

03[ DOCKER ]

Ephemeral containers

Containers are stateless; personality and state live on mounted volumes. SeedDir seeds once, never overwrites.

04[ NIXOS ]

Fully declarative

Everything in one flake. nixos-rebuild switch applies the fleet atomically — and rolls back.

05[ LOCKFILE ]

Reproducible fleet

flake.lock pins every input. Same commit = same agent fleet, every time. No drift, no surprises.

06[ TTS ]

Piper TTS ready

Built-in Piper TTS server with an OpenAI-compatible /v1/audio/speech endpoint on :5001.

07[ ISO ]

Bootable installer

Live USB ISO with a dialog TUI wizard — from USB stick to running agents in 10–15 minutes.

08[ AUDITD ]

Filesystem audit

hermes-auditd watches state dirs via fsnotify and logs every write to SQLite.

09[ TAILSCALE ]

Tailnet, nothing else

Pre-configured Tailscale + SSH module. Agents reachable on the tailnet, exposed to nothing else.

[ 03 / 08 ] · ARCHITECTURE
// architecture //

One brain. Unlimited tentacles.

Each agent is a Hermes AI process — an LLM-powered assistant with its own tools, memory, and identity. tentaflake gives every agent its own Linux user, state directory, Docker container, and API keys. Real OS-level isolation, not just a different folder in the same compose file. Add as many as you need — no limit.

NixOS Flake
flake.nix · configuration.nix
Tentaclecoding
userhermes-coding
state · 0700
/var/lib/hermes-coding
agenix/run/agenix/hermes-coding-env
Tentacleresearch
userhermes-research
state · 0700
/var/lib/hermes-research
agenix/run/agenix/hermes-research-env
+∞
any role · any count
no limit per host
3 examples shown · agents are infinitely composable
Shared services
Piper TTS
:5001
Tailscale
mesh VPN
Docker
runtime
agenix
secrets
[ 04 / 08 ] · COMPARISON
// comparison //

tentaflake versus the alternatives

Eight dimensions, four approaches to running agents on one box.

[ DIMENSION × APPROACH ]  [ 8 × 4 ]
Dimension
tentaflake
docker-compose
VM per agent
k8s namespace
01 Per-agent Linux user
✓ built-in
✗ shared
✓ heavy
~ pod SA
02 Declarative config
Nix flake
YAML
manual
YAML + Helm
03 Atomic rollback
✓ rebuild
✗
snapshots
rollout
04 Per-agent secrets
agenix
.env risk
per-VM
k8s secret
05 Encrypted-in-repo
✓ age
✗
✗
sealed
06 Filesystem audit
auditd
✗
✗
✗
07 Bootable installer
ISO wizard
✗
✗
✗
08 Resource overhead
low
low
high
high
// tentaflake wins 8 / 8 on isolation + declarative opstentaflake 8 · VM 2
[ 05 / 08 ] · THE MODULES
// the modules //

Composable NixOS modules

Each module configures one slice of the host. modules/default.nix aggregates them all — import it and override what you need.

01 / 08
[ NETWORKING ]

networking.nix

Hostname, nftables firewall, NetworkManager. Strict perimeter by default.

02 / 08
[ HARDENING ]

hardening.nix

Sysctl hardening, AppArmor, journald limits. Security baked in, not bolt-on.

03 / 08
[ TAILSCALE ]

tailscale.nix

Tailscale with SSH and tag:auto. Optional, off until you enable it.

04 / 08
[ TTS ]

piper-tts-server.nix

Local Piper TTS with an OpenAI-compatible API on port 5001.

05 / 08
[ FIRSTBOOT ]

hermes-firstboot.nix

USB env detection + first-boot TUI wizard for the live ISO.

06 / 08
[ NIX ]

nix-settings.nix

Flakes, automatic GC, trusted-users, binary substituters.

07 / 08
[ USERS ]

users.nix

Admin user in the wheel + networkmanager groups.

08 / 08
[ YOUR MODULE ]

your-module.nix

Fork the template, add your own module, import it in default.nix.

mkHermesAgent — options reference[ 12 fields ]
optiondefaultdescription
namerequiredAgent identifier — user, group, container, state dir
stateDir/var/lib/…Isolated state directory
imagehermes:latestOCI container image
envFilenullPath to .env file (injected via --env-file)
agenixFilenullPath to agenix-decrypted env file
seedDirnullSOUL.md, AGENTS.md, skills/ — seeded on first boot
settingsnullHermes config.yaml — model routing, TTS, toolsets
extraVolumes[ ]Extra host:container:mode mounts
autoStarttrueAuto-start with systemd
cmd["gateway"…]Container entrypoint
[ 06 / 08 ] · COOKBOOK
// cookbook //

Recipes for every use case

Guides, references, and examples to build with tentaflake.

$ [ 8 ]  all · guide · reference · example
[ guide ]01

Quick Start

Clone, define an agent, set secrets, and deploy in five steps.

Read more →
[ reference ]02

mkHermesAgent options

All 12 fields — name, stateDir, image, envFile, settings, and more.

Read more →
[ guide ]03

Agenix Secrets

Encrypt secrets in-repo with age — setup, architecture, troubleshooting.

Read more →
[ reference ]04

Available Modules

11 NixOS modules — boot, networking, hardening, tailscale, TTS, and more.

Read more →
[ example ]05

Two-Agent Setup

Coding assistant + web researcher, each with model routing and toolsets.

Read more →
[ guide ]06

Installer ISO

Build a bootable USB with a 12-step interactive install wizard.

Read more →
[ reference ]07

hermes-auditd

Go daemon — fsnotify watcher, debounce, SQLite (WAL), event model.

Read more →
[ guide ]08

Tailscale Networking

Reach agents on the tailnet with SSH — exposed to nothing else.

Read more →
$ tentaflake — common commands [ .SH ]
$ nix flake check # validate the flake
$ sudo nixos-rebuild switch --flake .#agent-host # deploy
$ sudo nixos-rebuild switch --rollback # roll back
$ docker ps --filter "name=hermes-" # list agents
$ docker exec -it hermes-coding hermes chat # chat
[ 07 / 08 ] · ROADMAP
// roadmap //

Where we are — and where we're going

v0.1.0 ships the core scaffolding. Here's what's done, what's being hardened, and what's on deck.

v0.1.0
shipped
[ SHIPPED ]Everything on this site
✓ Agent isolation model
✓ Docker containers per agent
✓ 11 NixOS modules
✓ Piper TTS server
✓ Tailscale + SSH module
✓ hermes-auditd Go daemon
✓ Bootable installer ISO
✓ mkHermesAgent function
v0.2.0
in progress
[ HARDENING ]Security & ops — 12 tracked issues
⟳ SSH hardening + fail2ban
⟳ Docker rootless mode
⟳ Kernel hardening sysctls
⟳ Nix daemon hardening
⟳ Agenix secrets integration
⟳ CI/CD security pipeline
⟳ nftables egress filtering
⟳ OPSEC docs & key rotation
8 modules · 4 critical · 2 high · 2 medium
v0.3.0
next
[ PLANNED ]Live ISO & standalone mode
○ Live USB — RAM-only agents
○ Web dashboard
○ Health monitoring UI
○ Multi-host orchestration
All 12 open issues tracked on GitHubView all issues →
[ 08 / 08 ] · SHIP IT

Fork it. Boot the ISO.
Declare your fleet.

A community template — keep it generic, add your agents, encrypt your secrets with agenix. MIT licensed.

★ Star on GitHubBack to top ↑