Troubleshooting

Browser shows a certificate warning

Expected while the server runs --self-signed (the only mode currently supported) — click through it. Agents connecting to a self-signed server need --insecure (POTARU_INSECURE=true).

Agent won't enroll: "invalid token"

• The enrollment token may have already hit its max_uses limit, or expired (--ttl, default 24h). Mint a new one.
• Check --server/POTARU_SERVER points at the tunnel address (host:7000 by default), not the admin HTTPS address (host:8443).

Agent shows offline in the dashboard

• Confirm the agent process is actually running (potaru run must stay in the foreground — it doesn't daemonize itself).
• Check the agent's logs (--verbose) for reconnect attempts — a network path issue between the agent and the server's tunnel port (:7000 default) is the most common cause.

"this agent already has an active session"

Only one live tunnel session per agent is allowed at a time. This usually means a previous agent process is still running (or hasn't been detected as dead yet) — stop it before starting a new one.

Shell opens but the command doesn't run right

The agent's default shell is $SHELL, falling back to /bin/bash, then /bin/sh. In a Docker container built on a distroless base, none of those exist — this is exactly why potaru's own client image uses alpine instead (see the Docker section of Install).

docker exec / privilege questions

The Docker client image runs as an unprivileged user (uid 65532), not root — docker exec <container> id will confirm this. See Security → Least privilege on the agent.