Getting started

Secure installed-host quickstart

Reach a secure first agent deployment on an installed host.

Explain this page

Explain Secure installed-host quickstart with

Source: docs/01-quickstart.md at e21be475a3af · docs version 0.4.37

Installed hosts default to the fail-closed balanced profile. This guide verifies that baseline. An agent remains offline unless its exact container name has an explicit broker policy. Model access uses the LLM broker; web access uses the separate research relay, never general internet access.

1. Install the external management policy

Replace the placeholder identity in docs/tailscale-policy.example.json, validate it in the Tailscale admin console, and install it before relying on Tailscale as the only management path. The policy must restrict both network grants and Tailscale SSH to the operator and tag:agent-host.

The default tailnet allow-all policy is not acceptable. Do not enable Funnel or publish an agent API with Serve. Protect the identity provider with hardware-backed MFA; plan Tailnet Lock with at least two signing nodes.

2. Declare a stopped capsule

Copy the current example:

sudo cp \
  /etc/nixos/my-agents.nix.example \
  /etc/nixos/my-agents.nix

The example contains stopped Hermes and ZeroClaw capsules, a stopped OpenClaw scaffold, and matching workers and Btrfs workspace quotas for Hermes/ZeroClaw. Remove the builder, worker, and quota entries for any runtime you do not need. OpenClaw creates no OCI container and refuses an explicit start; see adapter support limits.

autoStart = false stops automatic controller startup, but activation still creates enabled workspace filesystems and worker services. On an existing host, follow workspace migration before enabling quotas. Do not add envFile, agenixFile, hostPort, servePort, host networking, or literal secret values under balanced; evaluation rejects them.

3. Evaluate and build without activation

From /etc/nixos, resolve the installed hostname and build its toplevel:

hostname
nix build \
  .#nixosConfigurations.<hostname>.config.\
system.build.toplevel \
  --no-link

Review any assertion and the source diff. A successful build proves the candidate closure, not the live host.

4. Activate only in an approved window

Activation is an explicit host mutation. Once the exact host and build result are reviewed, the operator may run:

sudo nixos-rebuild switch \
  --flake /etc/nixos#<hostname>

Tentaflake never performs this step merely because evaluation succeeded.

5. Verify the activated posture

tentaflake status
tentaflake doctor --security
tentaflake doctor --security --json
sudo systemctl cat \
  docker-hermes-coding.service

For Podman, the unit prefix is podman-. A balanced capsule should show runsc, non-root user, cap-drop-all, read-only root, no-new-privileges, hardened tmpfs, and resource flags. Without a broker it also shows network=none, and the security doctor reports TFSEC-013. With a broker it shows one internal network, runtime virtual credentials, and no direct route. It should not report TFSEC-020; that finding means the corresponding disposable worker boundary is absent. TFSEC-021 means its persistent workspace has no managed hard size ceiling.

autoStart = true is intentionally rejected under balanced until the same container key has an enabled LLM broker, worker, workspace quota, and research relay. Keep the controller stopped while those policies are incomplete or while migrating an existing workspace.

6. Keep the agent stopped

Do not place real OpenAI, Anthropic, OpenRouter, GitHub, Firecrawl, or infrastructure credentials in the capsule. Without a scoped broker declaration, a balanced agent cannot perform external model calls. Web calls additionally require its research relay and the operator-configured Research service and VPN. To grant narrow access, follow brokered egress and web research, build, review the generated units and firewall rules, then activate deliberately. The secure adapter example combines the required declarations; actual vendor tool discovery and execution still need runtime evidence.

For a trusted development-only compatibility host, the intentional escape is:

tentaflake.security.profile = "dev";

That permits legacy direct credentials and networking but is explicitly not a security boundary for untrusted 24/7 agents. There is no silent fallback from balanced or strict.