Reference CLI, relay deployment, and conformance peer
End-to-end guide for driving Tendril identity, pairing, grants, relayed sessions, standalone tendril-relay, and the JSON stdio conformance peer.
tendril-cli ships two binaries built on the stateless relay and async runtime: tendril for interactive host and client administration, and tendril-conformance-peer for cross-language protocol test harnesses.
Running a standalone relay
Launch tendril-relay locally or build the rootless container defined in crates/tendril-relay/Containerfile:
cargo run -p tendril-relay -- --listen 127.0.0.1:8443 --host localhost
In production deployments, terminate TLS directly on tendril-relay (--tls-cert and --tls-key, serving wss://<host>/v1/relay and wss://<host>/v2/relay) or behind a trusted reverse proxy configured with --trusted-proxy <CIDR>. Right-to-left RFC 7239 Forwarded (falling back to X-Forwarded-For if absent) extraction runs only when the TCP peer matches --trusted-proxy, so reverse proxies should strip or overwrite untrusted client forwarding headers. Rate limits normalize IPv4-mapped addresses and group IPv6 addresses by /64 prefix alongside global --max-connections and --max-mailboxes caps.
Managed relay admission (Tiers 1-3 and --auth-scope)
Both /v1/relay and /v2/relay support stateless admission control (allowlist OR proof, not additive):
- Tier 1 (Allowlist):
--allow-mailbox <b64url_pub>or--allow-mailboxes-file <path>admits listed mailbox keys onregisterandacceptwithout an additional HMAC or ticket proof. An empty or comment-only file (0valid keys) fails closed at startup. - Tier 2 (Shared HMAC):
--auth-secret-file <path>(0600file permissions recommended) orTENDRIL_RELAY_AUTH_SECRETverifiestendril-relay-auth-v1\0HMAC-SHA256 proofs.tendril-relayreadsTENDRIL_RELAY_AUTH_SECRETonce at startup rather than stripping the process environment. - Tier 3 (
RelayTicket):--issuer-pub <b64url_pub>verifies JCS-canonical Ed25519RelayTicketproofs (tendril-relay-ticket-v1\0,role: register | dial | any,1..=86400sTTL,+-30sskew). Treat aRelayTicketas a bearer credential when shared over untrusted channels or logs unless scoped totarget_puband a short TTL. --auth-scope <all|register-only>: Defaults toallwhenever any admission mechanism is active (requiring admission on bothregisteranddial, checkingauthright after decode before mailbox lookup or epoch skew checks). Passing--auth-scopewith no allowlist, secret, or issuer fails closed;--auth-scope register-onlywith Tier 1 alone leavesdialopen because Tier 1 is peer-mailbox allowlisting.
# Mint a Tier 3 RelayTicket using tendril relay-ticket
tendril --state-dir ./issuer-state relay-ticket \
--relay-host relay.example --role dial --target-pub "<b64url_pub>" --ttl-secs 300
Endpoint lifecycle with tendril
Each endpoint isolates its 0o700 state directory containing 0o600 identity.json and roster.json files:
# 1. Initialize host and client identities
tendril --state-dir ./host-state init --host-id my-host
tendril --state-dir ./cli-state init
# 2. Start host listener (direct TCP, optional relay/embedded-relay/p2p/overlay/broker, and pairing code)
tendril --state-dir ./host-state serve --listen 127.0.0.1:0 --issue-code lan
# Optional multi-rung host serving (zero-setup P2P, managed relays, Wire v2, or wake hints):
# tendril --state-dir ./host-state serve --p2p --embedded-relay --wire-v2 --issue-code remote
# tendril --state-dir ./host-state serve --p2p-relay https://relay.example/ --p2p-relay-token-file ./p2p.tok --p2p-pkarr --ephemeral-p2p
# tendril --state-dir ./host-state serve --relay wss://relay.example --wire-v2 --relay-v2 --relay-auth-secret-file ./relay.sec
# tendril --state-dir ./host-state serve --p2p-local --overlay 127.0.0.1:0 --overlay-allow-non-tailnet --broker 127.0.0.1:0 --issue-code remote
# (Pass --p2p-local or TENDRIL_P2P_LOCAL=1 on serve/pair/dial for offline local P2P;
# --overlay rejects non-Tailscale CGNAT/ULA peer IPs by default unless --overlay-allow-non-tailnet is passed;
# --p2p-relay is repeatable (1..=8 URLs, or default/disabled) and disables n0 Pkarr/DNS by default unless --p2p-pkarr is passed;
# pass --p2p-relay-token-file (or TENDRIL_P2P_RELAY_TOKEN) for static iroh-relay bearer tokens, or
# --p2p-api-secret-file (or TENDRIL_P2P_API_SECRET) when built with p2p-iroh-services for RCAN tokens;
# pass --relay-auth-secret-file (or TENDRIL_RELAY_AUTH_SECRET) or --relay-ticket-file on serve/pair/dial for managed Tendril relays;
# pass --wire-v2 on serve/pair/dial for Wire 0x02 PAKE/pseudonymous sessions;
# --relay-v2 requires --wire-v2 AND --relay or --embedded-relay (--relay-host alone errors);
# pass --wake-url (requires --wire-v2), --wake-adapter <webhook|apns|fcm|unified-push> (default webhook),
# --wake-secret-file (or TENDRIL_WAKE_SECRET), --wake-auth-header-file, and --wake-pre-wake on dial for opaque wake hints;
# CLI secret files and --relay-ticket-file enforce regular non-symlink files <= 16 KiB with Unix 0600 permissions (mode & 0o077 == 0);
# pass --no-pkarr on default relay mode to opt out of Pkarr/DNS, or --include-direct-addrs for non-metadata ?addr= hints.)
# 3. Pair client using printed endpoint and code (prefer --code-stdin, --code-file, or TENDRIL_PAIR_CODE
# over --code in multi-user environments), then confirm SAS on both host and client
tendril --state-dir ./cli-state pair --endpoint 127.0.0.1:PORT --code-stdin <<< "TND-XXXX-XXXX"
# 4. Confirm peer on host and host pin on client (default deny; --sas is required unless passing --allow-no-sas), then mint scoped grant
tendril --state-dir ./host-state confirm <client_device_id> --sas "<sas>"
tendril --state-dir ./cli-state confirm my-host --sas "<sas>"
# Out-of-band fingerprint-only override:
# tendril --state-dir ./host-state confirm <client_device_id> --allow-no-sas
tendril --state-dir ./host-state mint <client_device_id> --cap fs.read
# 5. Connect, send data, verify liveness via encrypted PING/PONG, then revoke
tendril --state-dir ./cli-state dial --target my-host --endpoint 127.0.0.1:PORT \
--grant '<grant_json>' --message "hello-tendril"
tendril --state-dir ./host-state revoke <client_device_id>
Headless M2M enrollment and log redaction
Autonomous devices enroll without SAS interaction using serve --allow-enroll, single-use enrollment tokens (--token-file, --token-stdin, or TENDRIL_ENROLL_TOKEN, avoiding shell history / argv exposure), and optional external trust anchors. Unknown, expired, and already-burned interactive pairing codes normalize computation with a uniform Argon2id dummy verification pass and return "unauthorized" on the wire so responders do not oracle-distinguish code validity. Pass --redact-logs to tendril serve in shared environments so pairing_code, decrypted application payload utf8, and token_nonce are emitted as "<redacted>" instead of plaintext on stdout JSON logs:
# Register an external trust anchor (optional; omit for self-issued host tokens)
tendril --state-dir ./host-state anchor add ci-admin --signing-pub "<b64url_1984b_hybrid_pub>"
tendril --state-dir ./host-state anchor list
# Serve with opt-in M2M enrollment and redacted stdout event logs
tendril --state-dir ./host-state serve --listen 127.0.0.1:0 --allow-enroll --redact-logs
# Mint a single-use token (0o600 --out file) and enroll with mandatory host key pinning
# (--host-signing-pub accepts either the 1984 B b64url key or 32 B signing_pub_hash)
tendril --state-dir ./host-state enroll-token --target-host my-host --ttl-secs 900 --out ./token.json
tendril --state-dir ./runner-state enroll \
--endpoint 127.0.0.1:PORT \
--host-id my-host \
--host-static-pub "<b64url_host_static>" \
--host-signing-pub "<b64url_host_signing_or_hash>" \
--token-file ./token.json
# Mint application grants after enrollment (still default deny), revoke unused nonces, or rotate keys
tendril --state-dir ./host-state mint <runner_device_id> --cap fs.read
tendril --state-dir ./host-state revoke-token "<token_nonce>"
tendril --state-dir ./host-state anchor revoke ci-admin
tendril --state-dir ./host-state rotate
Once revoked, subsequent dial attempts fail closed on the host listener during session establishment, and active tendril serve sessions reload roster.json updates (under .roster.lock advisory locking) to terminate revoked peers immediately across ticks or incoming frames (0x04 REKEY, 0x01 DATA). tendril rotate re-signs any persisted self-issued CRL automatically under the new key so revoked tokens stay blocked across key rotation.
JSON stdio conformance peer (tendril-conformance-peer)
Cross-language SDK bindings spawn tendril-conformance-peer and exchange single-line JSON commands over stdin/stdout (stdout is flushed after every response):
| Command | Purpose |
|---|---|
init |
Initialize in-memory or state_dir-backed identity and roster |
serve_direct, serve_relay |
Bind direct TCP or relay WSS listener onto background accept queue |
issue_code |
Issue single-use LAN or remote pairing code |
add_trust_anchor, revoke_trust_anchor |
Manage M2M hybrid signing trust anchors and responder policy |
mint_enrollment_token |
Mint single-use M2M enrollment token JSON (enables self-M2M when targeting self) |
pair |
Run initiator (endpoint + code) or responder pairing/M2M exchange |
confirm, mint, revoke |
Transition peer state and mint default-deny signed grants |
connect, send, recv, rekey, close |
Drive Noise XXhfs session, data exchange, key ratchet, and close |
authorize |
Evaluate capability check and return structured AuditEvent |
shutdown |
Close active listeners/session cleanly and exit |
Connections
Local graphLinked from
- Add M2M SDK parity and transport hardeningLogs“Reference CLI, relay deployment, and conformance peer”
- Add Phase 6 M2M enrollment, single-use burn log, and v2 privacy ADRLogs“Reference CLI, relay deployment, and conformance peer”
- Add relay v1 spec, async runtime providers, and CLI demoLogs“reference CLI, relay deployment, and conformance peer”