# Secure installed-host quickstart

> Reach a secure first agent deployment on an installed host.

Canonical page: https://docs.tentaflake.dev/getting-started/quickstart/

> Source: [`docs/01-quickstart.md`](https://github.com/timfewi/tentaflake/blob/e21be475a3afc6e95c5087003edd0b7f780e4df4/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](https://docs.tentaflake.dev/configuration/research/), 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:

```bash
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](https://docs.tentaflake.dev/configuration/agent-adapters/).

`autoStart = false` stops automatic controller startup, but activation still
creates enabled workspace filesystems and worker services. On an existing host,
follow [workspace migration](https://docs.tentaflake.dev/configuration/workspace-quota/) 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:

```bash
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:

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

Tentaflake never performs this step merely because evaluation succeeded.

## 5. Verify the activated posture

```text
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](https://docs.tentaflake.dev/configuration/brokered-egress/) and [web research](https://docs.tentaflake.dev/configuration/research/),
build, review the generated units and firewall rules, then activate deliberately.
The [secure adapter example](https://github.com/timfewi/tentaflake/blob/e21be475a3afc6e95c5087003edd0b7f780e4df4/examples/adapter-secure.nix) 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:

```nix
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.

## Next reading

- [Security profiles and migration](https://docs.tentaflake.dev/security/profiles/)
- [Tailscale management policy](https://docs.tentaflake.dev/operations/tailscale/)
- [Operations and recovery](https://docs.tentaflake.dev/operations/recovery/)
- [Agenix boundaries](https://docs.tentaflake.dev/configuration/secrets/)
- [Brokered egress](https://docs.tentaflake.dev/configuration/brokered-egress/)
- [Disposable worker and approval](https://docs.tentaflake.dev/configuration/disposable-worker/)
- [Persistent workspace quota](https://docs.tentaflake.dev/configuration/workspace-quota/)
- [Threat model](https://docs.tentaflake.dev/security/threat-model/)
- [Agent adapters and support limits](https://docs.tentaflake.dev/configuration/agent-adapters/)