Mac: Hermes dashboard as a launchd service behind Tailscale Serve

The dashboard used to be started by hand as `serve --host 0.0.0.0`, so it
was reachable from the LAN and didn't survive a reboot or a Hermes update.
Now, following Hermes's docs:

- launchd agent local.hermes-dashboard runs `hermes dashboard` on
  127.0.0.1:9119 (KeepAlive, --skip-build since `hermes update` builds it).
- Tailscale Serve publishes it on https://cogitator-02.porgy-porgy.ts.net,
  tailnet only. No module exists for Serve; the task reads
  `serve status --json` and only sets it when it differs.
- Login: scrypt password hash and a real signing secret from the vault
  (the old secret was the literal text "$(openssl rand -base64 32)"); the
  plaintext password line is removed from .env since it overrides the hash.
- After Serve is set, the play checks /api/status demands the basic login;
  if not, it turns Serve off and fails.
- Hermes's Python no longer needs a firewall exception, so that's gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
PhilandClaude Opus 5.5 committed 2026-11-11 06:46:47 -07:00
1 parent fe268bd171
commit d617a2aa64
8 files changed
+176 -28

No files matched your search

+6
View File
@@ -18,3 +18,9 @@ mac_pmset:
disksleep: 0 # never spin down disks
autorestart: 1 # power back on after a power cut
womp: 1 # wake on network access
# Hermes's web dashboard: a launchd service listening on 127.0.0.1 only,
# published to the tailnet over HTTPS by Tailscale Serve.
hermes_dashboard_port: 9119
hermes_dashboard_url: "https://{{ ansible_host }}"
hermes_dashboard_username: admin
+14 -6
View File
@@ -11,15 +11,23 @@ Manages cogitator-02, an Apple Silicon Mac on the tailnet (`mac.yml`,
sleep, power back on after a power cut, wake on network.
- **Firewall** (tag `firewall`): macOS's application firewall on, with signed
software allowed automatically (SSH, BlueBubbles, AirPlay, Tailscale), no
stealth mode and no block-all. Hermes's own Python isn't properly signed, so
it's allowed explicitly (its web dashboard listens on port 9119). Any other
unsigned program that needs incoming connections must be added the same way,
or the firewall silently blocks it.
stealth mode and no block-all. Any unsigned program that needs incoming
connections has to be allowed explicitly, or the firewall silently blocks
it. (Nothing needs that today.)
- **Hermes dashboard** (tag `hermes-dashboard`): a launchd service
(`local.hermes-dashboard`) running `hermes dashboard` on 127.0.0.1:9119, and
Tailscale Serve publishing it at `https://cogitator-02.porgy-porgy.ts.net`,
reachable from the tailnet only. Login is username `admin` with the password
hash and signing secret from `vault_cogitator02`, written into
`~/.hermes/.env` (a plaintext password line there is removed, since it would
override the hash). After setting up Serve, the play checks the dashboard
demands a login through it; if not, it turns Serve off and fails.
Ansible logs in as `phil`. sudo needs phil's password, which is in the vault
as `vault_cogitator02.become_password`; only tasks with `become: true` use it.
phil deliberately doesn't get passwordless sudo, because Hermes Agent runs as
phil and takes commands over Telegram.
Not managed here: Hermes Agent (`~/.hermes`, self-updating git install,
launchd agent `ai.hermes.gateway`) and Tailscale.
Not managed here: Hermes Agent itself (`~/.hermes`, a self-updating git
install on the stable channel, launchd agent `ai.hermes.gateway`), its other
settings, and the Tailscale app.
+6
View File
@@ -0,0 +1,6 @@
- name: Restart Hermes dashboard
community.general.launchd:
name: "{{ hermes_dashboard_label }}"
state: restarted
# Nothing to restart in a dry run (on the first deploy the plist isn't there).
when: not ansible_check_mode
-22
View File
@@ -26,28 +26,6 @@
when: item.current not in firewall_current
become: true
# Hermes's own Python (ad hoc signed) serves its web dashboard on port 9119.
# Its path has a version in it, so every Python Hermes has installed is allowed.
- name: Find Hermes's Python
ansible.builtin.find:
paths: "{{ ansible_user_dir }}/.hermes/tools"
patterns: '^python3\.\d+$'
use_regex: true
recurse: true
depth: 3
file_type: file
register: hermes_python
- name: Allow Hermes's Python
ansible.builtin.shell: >-
{{ socketfilterfw }} --add {{ item.path | quote }} &&
{{ socketfilterfw }} --unblockapp {{ item.path | quote }}
loop: "{{ hermes_python.files }}"
loop_control:
label: "{{ item.path }}"
when: firewall_current is not search((item.path | regex_escape) ~ '\s*\n\s*\(Allow incoming')
become: true
- name: Turn the firewall on
ansible.builtin.command: "{{ socketfilterfw }} --setglobalstate on"
when: "'Firewall is enabled' not in firewall_current"
+105
View File
@@ -0,0 +1,105 @@
# Hermes never installs a service for its dashboard; this is the launchd
# version of the systemd unit in its docs (user-guide/features/web-dashboard).
# Login: username + scrypt password hash + a fixed signing secret, so sessions
# survive restarts. public_url makes it accept the Tailscale Serve origin.
- name: Dashboard login and public URL in Hermes's .env
ansible.builtin.lineinfile:
path: "{{ hermes_env }}"
regexp: "^{{ item.key }}="
# Single quotes: Hermes reads .env without interpolation, and the hash has $ in it.
line: "{{ item.key }}='{{ item.value }}'"
mode: "0600"
loop:
- { key: HERMES_DASHBOARD_BASIC_AUTH_USERNAME, value: "{{ hermes_dashboard_username }}" }
- { key: HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH, value: "{{ vault_cogitator02.dashboard_password_hash }}" }
- { key: HERMES_DASHBOARD_BASIC_AUTH_SECRET, value: "{{ vault_cogitator02.dashboard_secret }}" }
- { key: HERMES_DASHBOARD_PUBLIC_URL, value: "{{ hermes_dashboard_url }}" }
no_log: true
diff: false
notify: Restart Hermes dashboard
# A plaintext password overrides the hash, so it must not be there.
- name: No plaintext dashboard password in .env
ansible.builtin.lineinfile:
path: "{{ hermes_env }}"
regexp: "^HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="
state: absent
no_log: true
diff: false
notify: Restart Hermes dashboard
- name: Dashboard launchd service
ansible.builtin.template:
src: hermes-dashboard.plist.j2
dest: "{{ ansible_user_dir }}/Library/LaunchAgents/{{ hermes_dashboard_label }}.plist"
mode: "0644"
register: dashboard_plist
notify: Restart Hermes dashboard
- name: Dashboard running
community.general.launchd:
name: "{{ hermes_dashboard_label }}"
state: started
# In a dry run of the first deploy the plist doesn't exist yet.
when: not (ansible_check_mode and dashboard_plist is changed)
# Restart now on changes, so the login check below tests the new settings.
- name: Apply dashboard changes
ansible.builtin.meta: flush_handlers
# Tailscale Serve: tailnet-only HTTPS on https://<this Mac>.ts.net, proxied to
# the loopback dashboard. No Ansible module manages it, so read the current
# config and set it only when it differs. --bg keeps it across reboots.
# TAILSCALE_BE_CLI makes the app binary act as the CLI without a terminal.
- name: Read Tailscale Serve config
ansible.builtin.command:
argv: ["{{ tailscale_cli }}", serve, status, --json]
environment:
TAILSCALE_BE_CLI: "1"
register: tailscale_serve
changed_when: false
check_mode: false
- name: Serve the dashboard on the tailnet over HTTPS
ansible.builtin.command:
argv: ["{{ tailscale_cli }}", serve, --bg, --https=443, "http://127.0.0.1:{{ hermes_dashboard_port }}"]
environment:
TAILSCALE_BE_CLI: "1"
when: >-
(tailscale_serve.stdout | from_json).get('Web', {}).get(ansible_host ~ ':443', {})
.get('Handlers', {}).get('/', {}).get('Proxy', '')
!= 'http://127.0.0.1:' ~ hermes_dashboard_port
# The dashboard must ask for a login through Serve. If it doesn't, take it
# off the tailnet and stop.
- name: Check the dashboard login is on
when: not ansible_check_mode
block:
- name: Wait for the dashboard to answer through Tailscale Serve
ansible.builtin.uri:
url: "{{ hermes_dashboard_url }}/api/status"
return_content: true
register: dashboard_status
until: dashboard_status.status == 200
retries: 12
delay: 5
- name: Dashboard requires the username/password login
ansible.builtin.assert:
that:
- dashboard_status.json.auth_required | bool
- "'basic' in dashboard_status.json.auth_providers"
quiet: true
rescue:
- name: Take the dashboard off the tailnet
ansible.builtin.command:
argv: ["{{ tailscale_cli }}", serve, --https=443, "off"]
environment:
TAILSCALE_BE_CLI: "1"
- name: Stop here
ansible.builtin.fail:
msg: >-
The dashboard didn't answer or doesn't require a login through
{{ hermes_dashboard_url }}, so Tailscale Serve was turned off.
Check ~/.hermes/logs/dashboard.error.log on the Mac.
+4
View File
@@ -29,3 +29,7 @@
- name: Firewall
ansible.builtin.import_tasks: firewall.yml
tags: firewall
- name: Hermes dashboard
ansible.builtin.import_tasks: hermes-dashboard.yml
tags: hermes-dashboard
@@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- {{ ansible_managed }} -->
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>{{ hermes_dashboard_label }}</string>
<key>ProgramArguments</key>
<array>
<string>{{ ansible_user_dir }}/.local/bin/hermes</string>
<string>dashboard</string>
<string>--host</string>
<string>127.0.0.1</string>
<string>--port</string>
<string>{{ hermes_dashboard_port }}</string>
<string>--no-open</string>
<!-- hermes update builds the web UI; don't rebuild on every start -->
<string>--skip-build</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>HERMES_HOME</key>
<string>{{ ansible_user_dir }}/.hermes</string>
<key>PATH</key>
<string>{{ ansible_user_dir }}/.local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>ThrottleInterval</key>
<integer>30</integer>
<key>StandardOutPath</key>
<string>{{ ansible_user_dir }}/.hermes/logs/dashboard.log</string>
<key>StandardErrorPath</key>
<string>{{ ansible_user_dir }}/.hermes/logs/dashboard.error.log</string>
</dict>
</plist>
+3
View File
@@ -1 +1,4 @@
socketfilterfw: /usr/libexec/ApplicationFirewall/socketfilterfw
hermes_env: "{{ ansible_user_dir }}/.hermes/.env"
hermes_dashboard_label: local.hermes-dashboard
tailscale_cli: /Applications/Tailscale.app/Contents/MacOS/Tailscale