homassistant_chrony_addon/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Home Assistant add-on that provides an NTP server and client using Chrony. It includes a Flask-based web UI for monitoring synchronization status.

Development Environment

Use the devcontainer configuration for local development. The devcontainer uses the Home Assistant add-on development image and mounts the workspace at /mnt/supervisor/addons/local/.

To start Home Assistant with the add-on for testing:

supervisor_run

Ports exposed in devcontainer:

• 7123 → 8123 (Home Assistant)
• 7357 → 4357 (debug)

Architecture

Container Runtime: Alpine-based image using s6-overlay for process supervision.

Services (s6-rc.d):

• chrony: Main NTP daemon - reads /data/options.json, generates /etc/chrony/chrony.conf, runs chronyd -d
• webui: Flask app on port 8099 (or INGRESS_PORT env var) - provides status dashboard and API

Configuration Flow: Home Assistant writes add-on config to /data/options.json → chrony/run script parses with jq → generates chrony.conf → starts chronyd

Web UI (rootfs/var/www/):

• app.py: Flask app with routes for dashboard and API endpoints (/api/status, /api/options, /api/force-sync, /api/burst)
• Uses chronyc -c commands to get machine-readable status output
• Templates use Jinja2 with Home Assistant-style dark theme

Key Files

• config.yaml: Add-on metadata, schema, ports, privileges (SYS_TIME required for time sync)
• build.yaml: Architecture-specific base images
• Dockerfile: Installs chrony, jq, python3, py3-flask
• rootfs/etc/s6-overlay/s6-rc.d/*/run: Service startup scripts

Add-on Configuration Schema

Options defined in config.yaml:

• ntp_servers: List of {server: str, iburst: bool?}
• allow_clients: List of CIDR networks
• enable_ntp_server: bool
• log_level: debug|info|warning|error