Fail-closed controllers
Balanced controllers use non-root gVisor containers, read-only roots, dropped capabilities, bounded resources, private state, and no direct network.
main · devpre-1.0MIT
Isolated AI agents, declared with NixOS.
An open-source NixOS flake for isolated agents with explicit host policy, brokered egress, disposable workers, and reproducible operations.
One NixOS brain · Many AI tentacles.
3 · Read the evaluated result
schemaVersion = 1
[[agents]]
adapter = "hermes"
name = "assistant"
autoStart = false
[[agents]]
adapter = "zeroclaw"
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
A fixed-size workspace quota; private state is separate.
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 controllerselected adapter · 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- 01Declarein tracked installation-owned
tentaflake.toml - 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 documentation guides
- /llms-full.txtThe prose guides in one file
- /<page>.mdA Markdown twin of each prose guide
- /.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 resolved Tentaflake host through its authorized private management path.
- tentaflake-change-review
Review a concrete Tentaflake requirement, verification evidence and synchronized documentation.
- tentaflake-repo-guidance
Locate owning sources, guides and checks before changing Tentaflake.
[ 07 · agent adapters ]
Shared adapters. Explicit runtime status.
Hermes and ZeroClaw have native adapters; vendor acceptance remains pending. Generic OCI workloads are declared stopped and run offline without automatic startup or accepted model/Research integration. OpenClaw refuses startup; public Pi Durable entries remain stopped, with separately reviewed host admission available. Review adapter contracts and evidence.
Discover presets with tentaflake runtimes --json. Installed-layout agent plan|import prepares stopped additions without activation; consumer flakes edit and validate their own tracked TOML. Read the configuration 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 + Pi Durable
OpenClaw remains a refusal scaffold. Pi Durable needs explicit reviewed host admission; neither claim establishes live vendor or provider acceptance.
[ 08 · product roadmap ]
Explain: the product roadmap
Declarative agents. Explicit evidence.
The separately dated planning source describes priorities for onboarding, runtime acceptance, diagnostics and adapters. Consult the current pinned documentation for its exact source and evidence limits.
01
Priority 01
Keep TOML onboarding and installation simple without hiding Nix host policy, changing defaults or silently relocating state/accounting.
02
Priority 02
Complete actual vendor startup, model transport, Research discovery, execution mediation, lifecycle and restore acceptance for each runtime. Source fixtures alone do not establish support. OpenClaw remains a refusal scaffold, and Pi Durable one unless explicitly admitted; generic OCI remains offline without accepted model/Research hooks.
03
Priority 03
Improve bounded application readiness and diagnostics without replaying work or overriding explicit operator stops.
04
Priority 04
Add adapters through their own reviewed image, native hooks and evidence, not new shared security implementations or runtime-prefixed host services.
Planning snapshot · Source e6f3081. Plans are not release commitments.
[ 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?
Hermes and ZeroClaw have native adapters with vendor acceptance pending. Generic digest-pinned OCI workloads are declared stopped and can run offline, without automatic startup or accepted model/Research integration. OpenClaw is a refusal scaffold; public Pi Durable declarations remain stopped, while separately reviewed host admission can run its exact runtime. Provider acceptance remains separate.
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 per-boot 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. Each prose guide has a Markdown twin, the guides are available as one file, and guide chapters offer assistant prompts grounded in their Markdown. The documentation splash page is not a prose twin. Verify an assistant's answer against its cited guide.
Is tentaflake production-ready?
tentaflake is pre-1.0. Review the exact source revision, threat model, evidence gaps and residual risks, and validate the target host before relying on it. Development documentation is not a released support claim.
[ declare · verify · activate ]