Showing the changes to README.md (1 of 17 files). Show all
Unified · Split
| @@ -72,6 +72,8 @@ Inside the agent container: · 71 unmodified lines | ||
| 72 | 72 | hb status / hb doctor / hb versions |
| 73 | 73 | hb down # durable pause; the reconcile loop won't restart services |
| 74 | 74 | hb up |
| 75 | +hb services # status for portable custom service drop-ins | |
| 76 | +hb services-reload # reconcile custom services immediately | |
| 75 | 77 | hb gateway-enable --confirm-single-writer I_CONFIRM_NO_OTHER_GATEWAY_USES_THIS_IDENTITY |
| 76 | 78 | hb gateway-disable |
| 77 | 79 | hb verify-state |
| @@ -87,6 +89,54 @@ tx9 gateway enable <box> --confirm-single-writer · 9 unmodified lines | ||
| 87 | 89 | tx9 gateway disable <box> |
| 88 | 90 | ``` |
| 89 | 91 | |
| 92 | +### Portable custom services | |
| 93 | + | |
| 94 | +An executable regular file placed directly in | |
| 95 | +`~/.config/hermes-box/services.d/` defines a custom service. Names must match | |
| 96 | +`[a-z0-9][a-z0-9_-]{0,62}`; directories, symlinks, non-executable files, and | |
| 97 | +unsafe names are ignored and reported by `hb services`. Definitions live on | |
| 98 | +the portable `/data` volume, so they survive backup, import, and upgrade. | |
| 99 | + | |
| 100 | +Each file is executed directly by absolute path, without shell sourcing, | |
| 101 | +evaluation, arguments, or interpolation. Scripts must remain in the | |
| 102 | +foreground and should `exec` their daemon. For example: | |
| 103 | + | |
| 104 | +```bash | |
| 105 | +install -d -m 700 ~/.config/hermes-box/services.d | |
| 106 | +cat >~/.config/hermes-box/services.d/signal <<'EOF' | |
| 107 | +#!/usr/bin/env bash | |
| 108 | +exec signal-cli daemon | |
| 109 | +EOF | |
| 110 | +chmod 700 ~/.config/hermes-box/services.d/signal | |
| 111 | +hb services-reload | |
| 112 | +``` | |
| 113 | + | |
| 114 | +The existing 20-second workload loop also reconciles definitions | |
| 115 | +automatically. Each service is supervised independently with a bounded | |
| 116 | +restart delay; one crashing service cannot block the others. `hb pause` and | |
| 117 | +`hb down` synchronously stop all custom services and prevent restart, while | |
| 118 | +`hb up`/`hb resume` start them again. Disabling only the Hermes gateway does | |
| 119 | +not affect custom services. Container termination is forwarded through the | |
| 120 | +log supervisor to each foreground process. | |
| 121 | + | |
| 122 | +`hb services` distinguishes a stable foreground child (`running`) from a | |
| 123 | +live capture wrapper waiting to restart it (`restarting`). This is process | |
| 124 | +state, not an application health check; `hb doctor` cannot infer a generic | |
| 125 | +health contract for arbitrary service code. | |
| 126 | + | |
| 127 | +Service output uses the same rotating, redacted durable log pipeline as other | |
| 128 | +tx9-owned processes. Sources are distinct and collision-free: | |
| 129 | + | |
| 130 | +```bash | |
| 131 | +tx9 logs media-bot --source service-signal | |
| 132 | +tx9 logs media-bot --source all | |
| 133 | +``` | |
| 134 | + | |
| 135 | +Drop-ins have the same permissions and network/filesystem access as the | |
| 136 | +`agent` user. Treat installing one as installing executable code in the box; | |
| 137 | +the filename and regular non-symlink checks prevent accidental shell | |
| 138 | +evaluation or symlink execution, but do not sandbox trusted service code. | |
| 139 | + | |
| 90 | 140 | ## Logs and resource allocation |
| 91 | 141 | |
| 92 | 142 | Runtime output from the agent supervisor, Hermes gateway, and Executor is |