Skip to main content
pylon doctor runs a full health check on your Pylon installation. It verifies Docker, your agent image, channel credentials, Git auth, port availability, and per-pylon webhook reachability — then prints a summary of issues and recommendations.

​
Usage

pylon doctor
No arguments or flags.

​
Checks performed

CheckWhat it verifies
Config~/.pylon/config.yaml exists and is valid
DockerDocker daemon is running; prints version
Agent imageThe configured agent Docker image is built
Telegram botBot token is set and valid; bot API responds
Telegram chatChat ID is configured and bot has access
Slack botBot token is valid; bot is authenticated
Slack channelBot is invited to the configured channel
Git authSSH key for GitHub is configured, or gh CLI is authenticated
Agent authOAuth session (~/.claude/) or API key env var is set
PortConfigured port (default 8080) is available or already owned by Pylon
PylonsLists all constructed pipelines
Webhook reachabilityPer-pylon: sends a GET to the public webhook URL
systemd serviceWhether the Pylon user service is installed and active

​
Status indicators

Each line shows one of four statuses:
IndicatorMeaning
okCheck passed
FAILBlocking issue — fix before running pylon start
WARNNon-blocking recommendation
--Not configured (optional feature)

​
Example output

Pylon Doctor

Config .............. ok    ~/.pylon/config.yaml found
Docker .............. ok    running (v27.1.1)
Agent image ......... ok    pylon/agent-claude:latest built
Telegram bot ........ ok    connected (@MyPylonBot)
Telegram chat ....... ok    chat -1001234567890 accessible
Git (SSH) ........... ok    GitHub SSH key configured
OAuth session ....... ok    ~/.claude found
Port 8080 ........... ok    available
Pylons .............. 2 constructed (my-sentry, pr-review)
  my-sentry webhook ... ok    https://my-server.com/my-sentry reachable
systemd service ..... --    not installed (run `pylon service install`)

All checks passed. (1 recommendation)

​
Interactive fixes

Doctor can fix some issues interactively:
  • No channel configured — prompts to set up Telegram or Slack on the spot
  • Telegram chat ID missing or inaccessible — offers to auto-detect it (add bot to group, send a message)

​
When to run doctor

  • After first installation, before pylon start
  • When a pipeline stops receiving notifications
  • When a webhook is not being triggered from an external service
  • After changing bot tokens or rotating API keys