Device approvals (Warden)

With approvals on, a device that registers is not on your network yet. It waits in the Warden inbox; you decide.

Turn it on

Settings → Authentication → Peer Approval. The change is recorded in the activity log. Devices already on the network are not affected; every device that registers from now on waits.

People you already trust

With Trust signed-in users on (Settings → Authentication), a device enrolled by a person who signs in is admitted at once and the activity log records peer auto-approved: enrolled by a trusted signed-in user. Devices enrolled with a setup key still wait. Use it when your identity provider is the gate you trust and Warden is there for servers, contractors and unknown machines. Over the API the setting is settings.extra.peer_approval_trust_users.

Keys that skip the inbox

A setup key created with Skip device approval admits its devices immediately; everything else still waits. Each bypass is logged as peer auto-approved by setup key. See Setup keys.

What a waiting device can do

Nothing on the mesh. The control plane withholds its network map: it receives no peers, no routes, no DNS, and approved peers do not learn about it either. It is registered, it has an address, and it is isolated in both directions. Isolation is enforced by the control plane, not by the client, so a modified client gains nothing.

The Warden inbox

Warden in the sidebar lists every waiting device with its mesh address, operating system, how it enrolled (setup key or user) and when it was last seen.

Approve all admits every waiting device, one audit event each. The same actions exist on the Peers page under each row's menu, and the Pending Approvals filter shows the count.

Get told when a device is waiting

Under Settings → Authentication, with Peer Approval on, add the administrators who should hear about new requests:

E-mail needs the control plane's mail relay: set TZX_SMTP_HOST, TZX_SMTP_PORT, TZX_SMTP_USER, TZX_SMTP_PASSWORD, TZX_SMTP_FROM (and TZX_SMTP_TLS=starttls|implicit) in /opt/tzxmesh/app/.env, then restart the server. Any relay works: Resend, Postmark, Amazon SES, Google Workspace. Webhooks need nothing extra; set TZX_WEBHOOK_SECRET to have them signed. Private and loopback targets are refused, and at most 20 notifications per minute leave per account so a mass enrolment cannot flood you.

{
  "event": "device.pending",
  "sent_at": "2026-09-04T03:10:00Z",
  "device": {"account_id": "...", "id": "...", "name": "laptop-a", "hostname": "laptop-a",
             "os": "linux", "ip": "100.64.0.9", "enrolled_by": "setup key sales-request",
             "pending_since": "2026-09-04T03:09:58Z"},
  "console_url": "https://mesh.example.com/warden?peer=..."
}

Stale devices

Devices nobody admits should not pile up. Under Settings → Authentication, set Remove waiting devices after to a number of hours; a device that sits in Warden longer than that is removed automatically and the activity log records pending peer removed after the approval time limit. Leave it empty to keep devices until you decide. Revoking a device's approval restarts its clock. Over the API the setting is settings.extra.peer_approval_pending_ttl (hours, 0 = never).

Revoke later

From a peer's row menu choose Revoke approval. The device drops off the mesh within a sync cycle and returns to the inbox. Use it for a lost laptop or a machine you no longer trust; use Delete to remove it entirely.

Audit trail

Every step is an event in Activity: approvals enabled or disabled, device added, device approved, approval revoked, with who did it and when.

Automation

Everything Warden does is available over the API, so approvals can be scripted or wired into a ticketing flow:

curl -X PUT https://mesh.example.com/api/peers/<peer-id> \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"...","ssh_enabled":false,"login_expiration_enabled":true,"inactivity_expiration_enabled":false,"approval_required":false}'

Many at once, one audit event each:

curl -X POST https://mesh.example.com/api/peers/approvals \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"peer_ids":["<id-1>","<id-2>"],"approve":true}'
# → {"updated":["<id-1>","<id-2>"],"failed":[]}

Personal access tokens are created under your user menu.