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.

10 NixOS modules · Go audit daemon · installer + live ISO · MIT
Pattern A: Use this template — clone, edit, rebuild[ .NIX ]
clone>git clone https://github.com/timfewi/tentaflake
build>nix build .#installer-iso
deploy>sudo nixos-rebuild switch --flake .#agent-host
Pattern B: Flake Input ★ recommended[ FLAKE ]
{
inputs.tentaflake.url = "github:timfewi/tentaflake";
 
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
modules = [
tentaflake.nixosModules.default
{ tentaflake.hostName = "my-host" }
];
};
}
Read the docs →View on GitHub
[ BY THE NUMBERS ] · primitives compiled into one flake
01
∞
Agents per host
02
10
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 ]

Installer + live ISO

Two images: an installer that deploys to disk via a TUI wizard, and a live ISO that runs agents entirely in RAM — no install, no trace.

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 / 10
[ BOOT ]

boot.nix

systemd-boot configuration, EFI variables.

02 / 10
[ LOCALE ]

locale.nix

Timezone, locale settings, console keymap.

03 / 10
[ NETWORKING ]

networking.nix

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

04 / 10
[ HARDENING ]

hardening.nix

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

05 / 10
[ TAILSCALE ]

tailscale.nix

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

06 / 10
[ NIX ]

nix-settings.nix

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

07 / 10
[ USERS ]

users.nix

Admin user in wheel + networkmanager groups.

08 / 10
[ PACKAGES ]

packages.nix

curl + git — minimal server essentials.

09 / 10
[ TTS ]

piper-tts-server.nix

Local Piper TTS, OpenAI-compatible API on port 5001.

10 / 10
[ AUDITD ]

hermes-auditd.nix

Filesystem audit daemon — fsnotify watcher, debounced writes logged to SQLite.

mkHermesAgent — options reference[ 14 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
extraEnvironment{ }Extra env vars for the container
extraContainerConfig{ }Extra Docker options (merged deep)
autoStarttrueAuto-start with systemd
networkMode"host"Container network mode (host or bridge)
createUsertrueCreate the hermes-<name> system user/group
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 14 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

10 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 + Live ISO

Deploy to disk with the install wizard, or boot agents entirely in RAM from USB — no install, no trace.

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
✓ 10 NixOS modules
✓ Piper TTS server
✓ Tailscale + SSH module
✓ hermes-auditd Go daemon
✓ Bootable installer ISO
✓ Live agent ISO (runs in RAM)
✓ mkHermesAgent function
v0.2.0
in progress
[ HARDENING ]Security & ops hardening — 11 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 hardening modules · 4 critical · 2 high · 2 medium
v0.3.0
next
[ PLANNED ]Dashboard & orchestration
○ Web dashboard
○ Health monitoring UI
○ Multi-host orchestration
open issuestracked 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 ↑