Linux agent not connecting: diagnose it from the host
You installed the agent but the server never appears in the fleet — or it appears and immediately goes silent. Everything you need is in systemctl and journalctl.
What this looks like
You ran the install.sh one-liner with your project API key, the install finished — but the host never shows up in the AllStak fleet view, or it appears once and stops. The agent is a systemd service, so its state and logs are fully inspectable on the host itself.
Connection failures come in three flavors: the service is not running, the service runs but authentication fails (wrong or revoked key), or the service runs but cannot reach the ingest host over HTTPS — including the subtle case where clock skew breaks TLS validation.
Common root causes
Service not running or crash-looping
The allstak-agent systemd unit may have failed to start, crashed, or been stopped. systemctl status shows it instantly.
Wrong or revoked API key
The key passed at install time authenticates every send. A key from the wrong project, a typo, or a key rotated after install produces continuous auth failures in the agent logs.
Blocked HTTPS egress
The agent needs outbound HTTPS to the ingest host. Firewalls, security groups, and proxies that block or intercept that traffic stop the agent cold.
Clock skew or deliberate decommission
A system clock far from real time makes TLS certificate validation fail. Separately, hosts that were decommissioned from the dashboard stop reporting on purpose and stay stopped.
Step-by-step diagnosis
SSH into the host and work top-down: service, logs, key, network, clock.
- 1
Check the service state
Run systemctl status allstak-agent. Active (running) means move to logs; failed or inactive means start it with systemctl start allstak-agent and watch whether it stays up.
- 2
Read the agent logs
Run journalctl -u allstak-agent -n 100 and look for the failure pattern: repeated authentication errors point at the key, connection or TLS errors point at network and clock.
- 3
Verify the API key
Compare the key the agent was installed with against the current project key in the dashboard (keys look like ask_live_…). If it was wrong or has been rotated, re-run the install.sh one-liner with the correct key.
- 4
Test HTTPS egress to the ingest host
From the host, curl the ingest host over HTTPS and confirm you get an HTTP response rather than a timeout or TLS failure. Fix firewall rules, security groups, or proxy allowlists as needed.
- 5
Check the system clock
Run timedatectl and confirm the time is correct and NTP synchronization is active. A skewed clock makes every TLS handshake fail — sync it and restart the agent.
- 6
Rule out a decommissioned host
If this host was previously deleted/decommissioned from the dashboard, the agent stops on purpose and will not revive on its own. If you intend to monitor it again, re-enroll by running the install.sh one-liner with your project key.
Prevent it from recurring
- After every install, confirm the host appears in the fleet view before closing the task.
- Keep NTP synchronization enabled on all hosts — clock skew breaks more than monitoring.
- When rotating a project key, plan a re-install pass across the fleet in the same window.
- Bake the install one-liner into your server provisioning so new hosts enroll automatically.
- Leave agent auto-update on — releases are signed and keep the fleet current without manual rounds.
Still stuck?
If the service runs, the key matches, egress works, and the clock is synced but the host still does not appear, check the AllStak status page, then email [email protected] with the hostname, your project name, and the last 50 lines of journalctl -u allstak-agent (redact anything sensitive).
Frequently asked questions
How do I install the agent in the first place?
One curl command: the install.sh one-liner from the dashboard, run with your project API key. It installs the lightweight Rust agent as a systemd service and the host appears in the fleet view within minutes.
Where do I see why the agent is failing?
On the host: systemctl status allstak-agent for the service state and journalctl -u allstak-agent for the logs. Auth errors mean the key; connection/TLS errors mean network or clock.
I deleted the host from the dashboard — why did the agent stop?
That is intentional: decommissioning a host stops its agent so deleted servers do not keep reporting. To monitor the host again, re-enroll it by re-running the install one-liner.
Does the agent need any inbound ports open?
No — the agent only makes outbound HTTPS connections to the ingest host. You never open inbound ports for it.
Explore more
By framework
Compare
From curl to fleet visibility
One command installs the lightweight Rust agent — CPU, memory, disk, processes, CVEs, and security events stream into a live fleet view. Start free.