Skip to content
Tyr

Connecting an agent

Enrollment is a three-step process:

  1. Create an enrollment token on the server.
  2. Install the agent on the host.
  3. Agent registers on first boot and receives a client certificate.

1. Create an enrollment token

Terminal window
tyr enrollment-token create --label "laptops-2026-q2" --max-uses 50 --expires-hours 168

Output:

enrollment token: tyr_et_a8d7f3e2c1b9...
  label:       laptops-2026-q2
  max_uses:    50
  expires_at:  2026-04-27T10:45:02Z


Store this value — it will not be displayed again.

Token hygiene:

  • Short TTLs by default — treat them like one-time passwords.
  • One token per fleet/environment (laptops, ci-runners, prod-workers) so you can revoke independently.
  • The token is hashed (argon2id) on the server — you get the plaintext only once.

2. Install the agent

On the target host:

Terminal window
curl -sSL https://raw.githubusercontent.com/terranchi/tyr/main/scripts/install.sh \
  | sudo bash -s -- \
      --component agent \
      --server https://tyr.example.com:7700 \
      --token  tyr_et_a8d7f3e2c1b9... \
      --name   $(hostname)

What it does:

  • Downloads the tyr-<arch>-linux.tar.gz matching your kernel architecture.
  • Installs /usr/local/bin/tyrd and /usr/local/bin/tyr.
  • Writes /etc/tyr/tyrd.yaml (config) with the token.
  • Installs /etc/systemd/system/tyr-agent.service, enables and starts it.

3. Verify

  1. On the agent host:

    Terminal window
    sudo systemctl status tyr-agent
    sudo journalctl -u tyr-agent -f

    You should see enrollment succeeded and policy loaded.

  2. From anywhere with CLI access:

    Terminal window
    tyr agent list

    Output:

    ID                                    NAME           STATUS   LAST_SEEN
    4f27e3c1-ab89-...                     my-host        online   5s ago

  3. Tail live events to confirm:

    Terminal window
    tyr audit tail --agent my-host

What happens under the hood

sequenceDiagram
    participant T as tyrd (first boot)
    participant S as tyr-server
    T->>S: 1. register(agent_name, csr, token)
    Note over S: validates token, signs CSR
    S-->>T: 2. cert + agent_id
    T->>S: 3. gRPC stream with mTLS

The enrollment token is consumed (uses incremented by 1). The agent persists its key + certificate to /var/lib/tyr/, so subsequent restarts re-use the same identity.

Re-enrolling

If /var/lib/tyr/ is wiped, the agent will attempt re-enrollment. You’ll need a valid token again. If you want to force a fresh identity:

Terminal window
sudo systemctl stop tyr-agent
sudo rm -rf /var/lib/tyr/*
sudo systemctl start tyr-agent   # uses token from /etc/tyr/tyrd.yaml

→ Next: Writing policies · Agents concept