Fail-closed controllers
Non-root gVisor containers, read-only roots, empty capabilities, bounded resources, private state, and no direct network.
v0.4.37pre-1.0MIT
Isolated AI agents, declared with NixOS.
An open-source NixOS flake for running Hermes and ZeroClaw with fail-closed containers, brokered egress, disposable workers, and reproducible operations.
One NixOS brain · Many AI tentacles.
3 · Read the evaluated result
{ mkHermesAgent, mkZeroClawAgent, ... }:
[
(mkHermesAgent { name = "assistant"; autoStart = false; })
(mkZeroClawAgent { name = "researcher"; autoStart = false; })
]- runtime
- gVisor
- user
- non-root
- root filesystem
- read-only
- capabilities
- none
- network
- none until brokered
- provider key
- never in the capsule
The installed default. A setting that would weaken the sandbox makes the configuration fail to build instead.
balanced- Default for agents that run unattended. Each runs sealed in its own sandbox and reaches models only through the LLM broker and the web only through the research relay.
dev- For trusted local development. The container policy is off, so it is not a security boundary.
strict- Reserved for future high-risk work. It needs a separate-kernel boundary that is not built yet, so the configuration does not build; there is no fallback.
- platform
- NixOS · x86_64-linux
- controllers
- Hermes + ZeroClaw
- default profile
- balanced
- license
- MIT
- docs
- human + agent readable
[ the agent world · illustrated ]
A shared host. An environment for each agent.
Each controller has its own illustrated capsule and service paths.
- LLM broker
Exact models and budgets; provider keys stay on the host.
- Research relay
A separate Unix socket to the pinned research service.
- Worker
Queued tool jobs in a disposable environment without egress.
- Workspace
Persistent state with a fixed-size filesystem quota.
The blue tentacles represent Tentaflake’s environment; they are not additional network routes.
Illustrated balanced topology, not live activity or security evidence. dev removes the container policy and is not a security boundary. Profile limits.
[ 01 · boundaries first ]
Explain: the isolation boundaries
Useful agents without ambient authority.
Every capability is declared at the layer that can actually enforce it. Unknown runtime evidence stays unknown instead of becoming a green status.
Narrow model access
A per-agent LLM broker enforces exact models, request and daily budgets, and credential substitution. The provider key never enters the capsule.
One path to the web
Web access goes only through the pinned secure-research-tool relay. Provider-hosted web tools are rejected, and retrieved content stays untrusted.
Bounded state and work
Fixed-size Btrfs workspaces, optional private-state quotas, disposable offline workers, explicit approvals, and encrypted backups. Review storage limits and migration.
[ 02 · architecture ]
One host. Separate control paths.
The controller never receives the host runtime socket or a real provider credential. Model calls, web research, tool execution, and persistent storage each have a distinct enforcement layer.
Explore the architecture- 01NixOS hostdeclarative policy · systemd · OCI runtime
- 02Agent controllerHermes or ZeroClaw · gVisor capsule · no ambient network
- 03aLLM brokerexact models, budgets, virtual keys03bResearch relaypinned secure-research-tool03cWorkerdisposable, offline, behind approval03dStoragebounded workspace · optional state quota
[ 03 · security evidence ]
Explain: the security claims
Claims stay attached to evidence.
A successful build proves the candidate closure, not the live host. tentaflake keeps configured policy, live evidence, and unknowns apart.
Read the threat modelMachine-readable posture
tentaflake doctor --security separates configured policy, live evidence, warnings, and unknowns.
Negative integration tests
An external attacker node exercises denied ports, metadata access, direct DNS, private ranges, resource ceilings, and reboot recovery.
Documented non-goals
The threat model does not claim prompt-injection resistance, daemon-level UID remapping, a separate kernel, or deployment proof from evaluation alone.
[ 04 · start safely ]
Choose the path that matches your host.
Install a dedicated host
Build the installer ISO, test it in a disposable UEFI VM, then install to an explicitly selected disk.
Open the install guideAdd tentaflake as an input
Import the module, declare a stopped capsule, evaluate and build first, then activate in a controlled window.
Read the secure quickstart- 01Declarea stopped capsule in
my-agents.nix - 02Build
nix buildthe toplevel, without activation - 03Activate
nixos-rebuild switchin an approved window - 04Verify
tentaflake doctor --securityon the live host
[ 05 · agent-native ]
Explain: using AI with tentaflake
Written for people. Readable by agents.
The documentation is plain text at predictable URLs, pinned to an exact source commit. Point Claude, ChatGPT, Gemini, or your coding agent at it and let it explain any chapter. Then check its answer against the page it cites.
- /llms.txtIndex of every documentation page
- /llms-full.txtThe complete documentation in one file
- /<page>.mdA Markdown twin of every page
- /.well-known/agent-skills/Skill discovery index with digests
Read https://docs.tentaflake.dev/llms.txt, then the install guide and the secure quickstart it links to. Ask me about my hardware and whether this is a new machine or an existing NixOS host. Then write a step-by-step plan. Do not run any command that formats a disk or activates a configuration.An assistant can be wrong. Building is not activating: disk writes, nixos-rebuild switch, and credentials stay with the operator.
[ 06 · skills ]
Explain: the tentaflake skills
Skills your agent can load.
A skill is a short instruction file an agent loads when a task matches it. Install the tentaflake skill into Claude Code, Codex, Cursor, Gemini CLI, or another compatible agent, and it knows where the docs live and which steps it must leave to you.
published by this site
tentaflake
Maps tasks to documentation pages and carries the rules that hold everywhere: stay on balanced, keep secrets out of Nix, and never activate without approval.
npx skills add \
https://tentaflake.dev/.well-known/agent-skills/tentaflake/SKILL.mdBundled with the repository
- handle-the-host
Inspect or maintain a deployed Tentaflake host through its authorized Tailscale SSH management path.
- hermes-config-manager
Change or diagnose declarative Hermes settings while preserving Tentaflake's read-only configuration and broker boundaries.
- hermes-memory-personality
Maintain one Hermes instance's memory, personality and seeds without overwriting runtime state or exposing private context.
- hermes-provider-setup
Configure or diagnose Hermes model access through Tentaflake's host-held LLM broker credentials and exact model policy.
- hermes-tools-config
Adjust Hermes tools and output limits without bypassing Tentaflake's Research or disposable-worker policy.
- tentaflake-change-review
Review a Tentaflake change for a concrete requirement, proportionate verification, synchronized docs and a complete PR.
- tentaflake-repo-guidance
Locate the owning source, guide and checks before changing Tentaflake modules, adapters, CLI or installer.
[ 07 · agent adapters ]
Shared adapters. Explicit runtime status.
Hermes and ZeroClaw retain their existing integrations through mkAgent and compatible legacy builders. Generic OCI definitions use the same containment but remain stopped pending capability admission; model and Research hooks are not accepted. OpenClaw is registered as a stopped scaffold. Review the adapter contracts and acceptance gaps.
Discover presets with tentaflake runtimes --json. On installed hosts, agent template and agent validate|plan|import prepare stopped additions without rebuilding, activating, or starting services. Read the onboarding workflow.
Hermes
A capable general agent controller with a dedicated non-root identity and private workspace.
ZeroClaw
A compact autonomous runtime held to the same final container policy and broker boundary.
OpenClaw · stopped scaffold
The adapter exists, but creates no OCI container and refuses startup. A reviewed image, model transport, Research discovery, and isolated execution still need runtime acceptance.
[ 08 · product roadmap ]
Explain: the product roadmap
From isolated agents to AI employees.
The delivery order: a common isolated runtime and installed-host onboarding, then coding-agent acceptance, employee profiles, controlled business connections and company workflows. Read the release-pinned guides for delivered foundations; remaining milestones describe future capabilities.
M01–M02
Runtime & coding acceptance
Planned- M01Add an agent on an installed host without changing security code
- M02Two different agents perform repository work inside the same enforced boundary
M03–M04
Employees & isolated contexts
Planned- M03Manage people, teams, personas and permissions
- M04One employee can safely perform many roles
M05–M07
Connections & collaboration
Planned- M05Controlled business access and external effects
- M06Useful coverage of everyday company programs
- M07Autonomous multi-step work with human participation
M08–M10
Operations, console & release
Planned- M08Observable and recoverable unattended operation
- M09One place to manage employees and business work
- M10Clearly documented, tested support and upgrades
GitHub snapshot · Planning source e21be47. Delivery gates describe dependencies; dates and release versions are not promised.
[ 09 · direct answers ]
Questions, answered precisely.
What is tentaflake?
tentaflake is an open-source NixOS flake template for operating isolated AI agent controllers on hardware you manage. It provides the host, container, policy, worker, storage, and verification layers; it does not implement an agent model or hosted control plane.
Which agent runtimes are supported?
The 0.4 release line integrates Hermes and ZeroClaw through mkAgent and compatible runtime-specific builders, with the same final container security policy. Generic digest-pinned OCI definitions and preset discovery are available, but generic workloads remain stopped pending capability admission; model and Research hooks are not accepted. OpenClaw is only a stopped scaffold: no runtime image, model transport, Research discovery, or worker routing has been accepted. Review the adapter guide for support and evidence limits.
What does balanced security mean?
Balanced agents run non-root through gVisor with a read-only root filesystem, no capabilities, bounded resources, no published ports, and no direct network. Automatically started controllers also require an exact LLM broker, disposable worker, fixed-size workspace, and research relay declaration.
Does tentaflake include an LLM provider?
No. You supply an approved provider or local endpoint. Real provider credentials stay on the host and enter the broker through runtime-only systemd credentials. An agent receives a short-lived virtual credential scoped to its declared policy.
Can an agent browse the web?
Only through the pinned secure-research-tool relay, which you configure and enable per agent. Native web tools, provider-hosted web search, and the legacy fetch broker are disabled for research agents, and retrieved content stays untrusted.
Can my AI assistant read the documentation?
Yes. Every documentation page has a Markdown twin, the whole documentation is available as one file, and each chapter opens in Claude, ChatGPT, Gemini, Perplexity, Le Chat, or Grok with a prompt that points at that page. Verify what an assistant tells you against the page it cites.
Is version 0.4 production-ready?
tentaflake is explicitly pre-1.0. The repository documents enforced controls, evidence gaps, residual risks, and a deployment acceptance checklist. Pin a release, read the threat model, and validate the exact target host before relying on it.
[ declare · verify · activate ]