This page mirrors the Agent Setup wizard in the dashboard (
/clm/agent-setup). Copy commands from either side — they’re identical.Prerequisites
| Requirement | Value |
|---|---|
| Agent API Key | Create one in Settings → API Keys → New key with type agent. Shown once. |
| Collector URL | https://collector.tigertrust.io (or your self-hosted Collector) |
| Supported OS | Debian/Ubuntu · RHEL/CentOS · Windows Server 2016+ · macOS 12+ |
| User | root or a service account that owns the paths you plan to manage |
Quick install (one script, any Linux)
Run the installer
tigertrust-agent, writes /etc/tigertrust/config.yaml, and enables the systemd service.Installation methods
Choose the flow that matches your platform. All flows land on the sametigertrust-agent binary and /etc/tigertrust/config.yaml.
- Linux (any distro)
- Windows
- Manual (tarball)
- Docker
The Behind the scenes this adds the apt/yum repo, installs the Manual package-manager install (if you want to control the repo yourself):Then create the directories, drop in a config file (there’s no
install.sh script auto-detects apt (Debian/Ubuntu) vs dnf/yum (RHEL/Fedora/CentOS/Amazon Linux) and picks the right package source. It also detects amd64 vs arm64 and pulls the correct binary. Use this path for every Linux target — bare metal, VM, container-host, edge box.Run the installer with your credentials
tigertrust-agent package, writes /etc/tigertrust/config.yaml, and runs systemctl enable --now tigertrust-agent.configure subcommand — the agent reads YAML), and start the service:Verify the install
Check service status
Tail agent logs
The install.sh script
The Linux flow above is what the single install.sh runs internally. It’s fetched from https://releases.tigertrust.io/tigertrust-agent/scripts/install.sh and:
- Detects the platform (
/etc/os-release,uname -m) — supportsamd64(x86_64) andarm64(aarch64). - Detects the package manager:
apt(Debian/Ubuntu) ordnf/yum(RHEL/Fedora/CentOS/Amazon Linux). Errors out on distros without either. - Adds the correct repo (apt sources file or
.repofile), imports the GPG key. - Installs the
tigertrust-agentpackage. - Creates the
tigertrustservice user and chowns/etc/tigertrust,/var/lib/tigertrust(keys/,tpm/), and/var/log/tigertrustto it. - Writes
/etc/tigertrust/config.yamlfrom the flags you passed. - Registers the systemd unit and starts it (only when
--collector-url+--api-keywere both supplied).
install.sh is Linux-only by design. Windows requires the MSI (different privilege model, different service manager) — use the Windows tab. macOS uses Homebrew (brew install tigertrust/tap/agent).Non-root operation
The agent daemon runs as an unprivilegedtigertrust user — never as root. The installer needs root once (to add the repo, install the package, and register the systemd unit), but the running process is dropped into a service account with:
| Path | Owner | Mode |
|---|---|---|
/etc/tigertrust/ | tigertrust:tigertrust | 750 |
/etc/tigertrust/config.yaml | tigertrust:tigertrust | 640 |
/var/lib/tigertrust/ | tigertrust:tigertrust | 750 |
/var/lib/tigertrust/agent-id | tigertrust:tigertrust | 600 |
/var/lib/tigertrust/keys/ | tigertrust:tigertrust | 700 |
/var/lib/tigertrust/tpm/ | tigertrust:tigertrust | 700 |
/var/log/tigertrust/ | tigertrust:tigertrust | 750 |
NoNewPrivileges=true, ProtectSystem=strict, ProtectHome=true, PrivateTmp=true, and ReadWritePaths=/var/lib/tigertrust /var/log/tigertrust.
Custom service user. If you want to bind the daemon to your own user (e.g. run as deploy who already owns the paths you’re deploying certs to), edit the systemd unit’s User= / Group=, chown the paths above to that user, and systemctl daemon-reload && systemctl restart tigertrust-agent. The daemon will honour whatever uid it inherits.
Rootless container. For Docker/Kubernetes deployments, run the container as a non-root uid and mount /etc/tigertrust, /var/lib/tigertrust, /var/log/tigertrust volumes owned by that uid. The container image is built with a non-root tigertrust user (uid 1000) by default.
What the installer creates
install.sh creates every directory the agent needs before starting the service, so you don’t hit permission denied on first heartbeat:
/var/lib/tigertrust/— the agent id (agent-id), key material (keys/), and TPM handle cache (tpm/) all land here. Created withmkdir -pand chowned to the service user./var/log/tigertrust/— created and chowned./etc/tigertrust/config.yaml— templated from--collector-url/--api-key/--agent-name. Chmod640./etc/systemd/system/tigertrust-agent.service— systemd unit with the non-root hardening flags above.
There is no
tigertrust-agent configure command. The agent is configured purely via the YAML at /etc/tigertrust/config.yaml. install.sh writes it for you; if you skip the installer, drop a config.yaml from the example template yourself and restart the service.install.sh (e.g. custom Ansible / Puppet), replicate those four items yourself. Otherwise the agent will fall back to inferring a home directory, and on read-only filesystems it will refuse to persist the agent id — you’ll see a fresh registration on every restart.
Capabilities
Agents advertise what they support. A discovery-only agent claims different capabilities than a data-center agent that also deploys certs. Edit/etc/tigertrust/config.yaml and restart:
Related
Agents and Collector
The pull-based architecture, task types, and enrollment flow.
Discovery
What the filesystem, keystore, and network scans actually look at.
Certificate renewal
End-to-end CSR generation and deployment during renewal.
Troubleshooting
Common enrollment and connectivity issues.