Agent Not Appearing in Dashboard

Steps to diagnose when your deployed agent doesn't show up in KubeWatch.

If you've deployed the agent but it doesn't appear in the dashboard within 60 seconds, work through these checks in order.

Check 1: Is the API key correct?

Verify the KUBEWATCH_API_KEY environment variable is set to the exact key from Settings → API Keys. Even a single extra space or missing character will cause authentication to fail.

Docker:

docker inspect kubewatch-agent | grep -A5 KUBEWATCH_API_KEY

Kubernetes:

kubectl get pod -n kubewatch -l app=kubewatch-agent -o jsonpath='{.items[0].spec.containers[0].env}'

Self-hosted and seeing `registration failed: register failed with status 401: {"error":"invalid api key"}` even though you're sure the key is correct? Check that `serverURL` (or `KUBEWATCH_SERVER_URL`) is actually set. It defaults to the hosted KubeWatch Cloud gateway, so a self-hosted agent deployed without it silently registers against the wrong server, one that has never seen a key your own self-hosted instance issued. See [Kubernetes Agent](/agents/kubernetes) or [Docker agent](/agents/docker-standalone) for the self-hosted install command.

Check 2: Can the agent reach the gateway?

From the agent host, test connectivity to the gateway:

curl -v https://YOUR_KUBEWATCH_URL/health

Expected response: HTTP 200 with a JSON body. If this fails, there's a network or DNS issue, not a KubeWatch configuration problem.

For self-hosted installations:

curl -v https://your-domain.com/health

Check 3: Is outbound port 443 open?

The agent needs outbound TCP to port 443. On many servers, outbound traffic is allowed by default, but some environments have restrictive egress rules.

nc -zv YOUR_KUBEWATCH_URL 443

If this times out, contact your network administrator to allow outbound HTTPS from the agent host.

Check 4: Check agent logs

Docker:

docker logs kubewatch-agent

Kubernetes:

kubectl logs -n kubewatch -l app=kubewatch-agent --tail=50

Common error messages:

Log message	Cause	Fix
`invalid api key`	Wrong or revoked `KUBEWATCH_API_KEY`	Regenerate the key in Settings → API Keys, update the agent's env var
`unauthorized` (after the agent previously registered)	The agent's stored session token is no longer valid, usually because it was deleted from the dashboard	Delete the stale entry if it still exists, restart the agent so it registers fresh
`connection refused`	Gateway not reachable	Check URL and port 443 access
`certificate verify failed`	TLS issue on self-hosted with self-signed cert	The agent doesn't support skipping certificate verification. Install a valid TLS certificate on your gateway (Let's Encrypt via Caddy, for example); self-signed certificates aren't supported
`docker socket not found at /var/run/docker.sock`	Socket not mounted, or not readable by the agent's user	Add the volume mount to your docker run / compose command; see Check 5 below

Check 5: Is the Docker socket accessible?

The agent needs access to /var/run/docker.sock:

ls -la /var/run/docker.sock

Expected: a socket file owned by root with group docker:

srw-rw---- 1 root docker 0 Jun 16 10:00 /var/run/docker.sock

If the agent container is running as a non-root user without the docker group, it won't be able to read the socket. The simplest fix is to ensure the volume is mounted and the agent container runs with sufficient permissions.

Check 6: Is the agent already registered under a different name?

Check the dashboard agent list and look for an agent with a similar name or your server's hostname. It's possible the agent registered successfully but you're looking at the wrong organization or agent filter.

Still stuck?

Email [email protected] and include:

The output of docker logs kubewatch-agent (last 100 lines)
The result of curl -v https://YOUR_KUBEWATCH_URL/health from the agent host
Your agent deployment method (docker run / compose / helm)