Skip to content

v0.3.0: Remote Control server --name; /healthz for homelab monitors

Choose a tag to compare

View all tags
@cmmichael cmmichael released this 28 Oct 15:24
· 6 commits to main since this release
v0.3.0
9104e89

Why

  • The server's session had no proper title. The session claude remote-control creates at start appeared in claude.ai/code and the Claude app under a generated name (for example iris-lucky-orbit). con-ant/hass-addons#56 found the --name flag for this.
  • Monitors and the health check failed against the user check. With CLAUDE_WEB_AUTH on, anything that requested / got a 403. That included the image's own health check, which logged a refusal every minute on iris, and it would include any Uptime Kuma, Gatus or Homepage monitor. The health check also only showed that the front end answered, not that the terminal worked.

What

  • Server name. claude remote-control runs with --name "${CLAUDE_RC_SERVER_NAME:-<hostname>}".
  • Permission mode for app sessions. The new optional CLAUDE_RC_PERMISSION_MODE passes --permission-mode to the server, from add-on con-ant/hass-addons#46.
  • Matching the server. The watcher and the sessions list now find the server with or without flags.
  • /healthz. It answers 200 ok when ttyd accepts a connection and 503 when it doesn't. It skips the user check and logs nothing.
  • /healthz?full=1. The same status code with JSON detail: terminal, claude_code (the version), remote_control_server, update_watcher and auth. A stopped server usually means the Claude login lapsed, so a monitor can alert on it. It reports states only.
  • HEALTHCHECK. It calls /healthz with the front end on, and plain ttyd with CLAUDE_WEB_FRONT=false.
  • docs/monitoring.md. It covers:
    • Uptime Kuma: HTTP, JSON query, Docker health, and AutoKuma labels
    • Gatus
    • Homepage
    • Watchtower, with WATCHTOWER_TIMEOUT=30s so the clean stop finishes
    • Traefik, plus Authelia and Authentik forward auth in header mode

Tested

  • Unit tests: 11 of 11 pass. The new ones cover:
    • /healthz returns 503 with the terminal down
    • the JSON shape
    • no refusal is logged under Pomerium mode
    • the server is found when started with flags, which fails against the old exact-match code
  • Smoke test, in the built image: /healthz?full=1 reports every part up. The stand-in server now runs with exactly the real command line, claude remote-control ….
  • The flags are real. On Claude Code 2.1.308, claude remote-control --help lists --name and --permission-mode.

Labelled release:minor: new endpoints and settings.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R5XxmiR28R15untFmoAMDW

Image: ghcr.io/cmmichael/claude-code-remote-container:0.3.0 (also :0.3)
Digest: sha256:a8efd093c86d2be7557936d53a4f3dbe59e7e20ac69c6ee560360ee073c18a78
Changes: v0.2.0...v0.3.0

Assets 2
Loading