Make ctrlrelay portable across machines#121
Merged
oscarvalenzuelab merged 5 commits intomainfrom May 4, 2026
Merged
Conversation
…hs.repo_root
Two portability changes that let a single orchestrator.yaml run
unmodified on multiple machines.
node_id falls back to socket.gethostname() when missing, null, or
blank — heartbeats and session logs still get a meaningful per-node
label without forcing every operator to edit the file.
paths.repo_root + paths.owner_aliases let RepoConfig.local_path be
derived as ${repo_root}/${owner_aliases.get(owner, owner)}/${repo}.
Per-repo local_path still wins as an override for repos that don't
follow the convention. Without repo_root, the legacy behaviour
(local_path required per repo) is preserved.
Update the example file so new operators see node_id-defaults-to-hostname and paths.repo_root + owner_aliases as the recommended path. Pairs with the previous commit that introduced the schema. The live operator orchestrator.yaml is gitignored — re-run with the new schema locally (this machine's copy collapsed from 69 explicit local_paths to 20).
New 'ctrlrelay install launchd|systemd' command renders bridge and
poller service unit files from in-package templates, substituting
USER, HOME, CTRLRELAY_BIN, WORKDIR, LABEL_PREFIX, POLLER_INTERVAL,
and (when set) CTRLRELAY_TELEGRAM_TOKEN. Writes to the conventional
locations (~/Library/LaunchAgents on macOS, ~/.config/systemd/user on
Linux) and refuses to clobber existing files unless --force.
This replaces the docs.operations.md copy-paste flow where every
operator had to hand-edit /Users/$ME/... strings — a tax on portability
and a common source of broken plists. Templates live under
src/ctrlrelay/templates/{launchd,systemd}/ and ship in the wheel.
Unresolved template variables (typically CTRLRELAY_TELEGRAM_TOKEN
when the env var isn't exported at install time) are surfaced as a
warning rather than silently emitting a literal ${TOKEN} into the
plist.
configuration.md: node_id is now optional (defaults to hostname); paths gets repo_root + owner_aliases keys; repos[].local_path is conditional on whether repo_root is set. getting-started.md: drop node_id from the required-edit list and from the minimal config snippet (hostname picks it up automatically). operations.md: lead each platform section with 'ctrlrelay install launchd|systemd' as the recommended path; keep the full inline templates as a hand-write fallback. Drops the redundant repeat blocks that duplicated the install steps.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds three portability primitives so a single
orchestrator.yamlcan run unmodified across machines:node_iddefaults tosocket.gethostname()when missing, null, or blank. Heartbeats and session logs still get a meaningful per-node label without forcing every operator to hand-edit the file.paths.repo_root+paths.owner_aliasesletrepos[].local_pathbe derived as${repo_root}/${owner_aliases.get(owner, owner)}/${repo}instead of being hand-written for every entry. Per-repolocal_pathstill wins as override. Withoutrepo_root, the legacy behaviour (per-repolocal_pathrequired) is preserved.ctrlrelay install launchd|systemdrenders bridge + poller unit files from in-package templates and writes them to the conventional locations (~/Library/LaunchAgents/~/.config/systemd/user). Substitutes${USER},${HOME},${CTRLRELAY_BIN},${WORKDIR},${LABEL_PREFIX},${POLLER_INTERVAL}, and (when exported)${CTRLRELAY_TELEGRAM_TOKEN}. Refuses to clobber existing files unless--force. Replaces thedocs/operations.mdcopy-paste-and-edit-/Users/$ME flow.The example
orchestrator.yaml.exampleanddocs/{configuration,getting-started,operations}.mdare updated to surface the new conventions; the liveconfig/orchestrator.yamlis gitignored as operator state but on the contributor's machine it collapses from 69 explicitlocal_pathentries to 20.Test plan
pytest -q)ruff checkcleanunzip -lconfirmstemplates/launchd/*.plist.templateandtemplates/systemd/*.service.template)ctrlrelay install launchd --dry-runsmoke-tested locally