Agentina

Troubleshooting

Most agent issues fall into four buckets: activation failed, agent won't stay running, heartbeat is failing, or work isn't getting dispatched. Each section below opens with the symptom and ends with what to send if you need to file a ticket.

Where to find logs

The agent writes structured logs:

  • systemd (Linux): journalctl -u agentina -f
  • launchd (macOS): tail -f /var/log/agentina.log
  • foreground run: stdout/stderr of agentina run

State files live in /var/lib/agentina/. The keypair is under keypair/ with 0600 perms; the license JWT lives at license.jwt; the session bearer at bearer.json.

Activation issues

"invalid token" / 401

The activation token was wrong, expired, or already redeemed. Check in /portal/tokens — an unused token is marked as such; a redeemed one shows which agent claimed it.

Mint a fresh one. Tokens are single-use; the first machine to redeem claims it.

"network unreachable" / timeout

Probe the control plane directly:

bash
curl -fsSL https://cp.agentina.io/v1/health

Expect 200 ok. If you get nothing, your firewall or DNS is the problem — not the agent. The agent connects outbound on 443 only; if your network requires a proxy, set HTTPS_PROXYin the systemd unit's Environment= directive.

Agent won't stay running

First, what does systemd say:

bash
sudo systemctl status agentina
sudo journalctl -u agentina -n 200 --no-pager

Common patterns:

  • schema_version mismatch — you upgraded across a breaking change in the on-disk state format. Run agentina activate --forceto reseat the state.
  • install may be tampered — the on-disk public key doesn't match what the private key derives. The state directory has been edited out-of-band. Wipe /var/lib/agentina/ and re-activate with a fresh token.
  • fingerprint_mismatch — the machine's hardware signature drifted past the license's tolerance. See Machine binding.

Heartbeat is failing

The agent prints "heartbeat degraded" at info level on every failed beat. Read the next line up: the cause is one of:

  • network — outbound 443 is blocked, the DNS for cp.agentina.io is failing, or the control plane is down.
  • auth_failed — bearer expired and the refresh didn't land. After grace expires you'll need to re-activate.
  • stop — the control plane is deliberately asking the agent to halt. The reason code in the log says why.
If last_self_hash changes on disk between restarts and you didn't upgrade, treat that as evidence of tampering: stop the agent, capture the state directory, and file a ticket with severity high.

Filing a ticket

Attach diagnostic context automatically with --logs:

bash
agentina report \
  --subject "agent won't start after upgrade" \
  --message "Upgrade from 0.4.0 → 0.4.1 swapped the symlink but systemd refuses." \
  --severity high \
  --logs

The last 200 lines of /var/log/agentina/agentina.log ship along as JSON-attached context. See Support for the full flow.