For developers · Orchestrator
Satellites
On this page
A satellite is another machine that runs workers for the main host's dispatcher (spec 7.9).
Network and SSH live only in crates/core; no port is opened and tokens never leave the main host.
Pieces#
gitoodo satellite: persistent service onsatellite.sock(0600) holding worker PTYs.gitoodo satellite --stdiois a pipe to that socket (it starts the service when missing), so workers survive SSH drops.- Protocol: JSON lines, the same
cmd/reply/framevocabulary as the dispatcher socket (dispatcher_rpc.rs), plushello,spawn,kill,subscribe,ask,ask_done. A bridge session runs requests in a row;subscribeandattachturn it into a stream. - Bridge: system
ssh -o BatchMode=yes ... -- <target> gitoodo satellite --stdio(GITOODO_SSHreplaces the program, used by tests). gitoodo host add <name> <ssh-target>: connects, compares versions, saves{name, ssh}only. A version mismatch is a clear error with the check command (ssh <target> gitoodo --version).- Dispatcher: polls every host (20 s), offers satellites as host candidates, starts workers with
spawn(the satellite creates the worktree in its own clone). Unreachable host: no new work, leases wait for the grace and are then released (lease_action). gitoodo attach [<host>] <issue>: raw terminal, detach with Ctrl-], the worker keeps running.- Questions:
gitoodo askon a satellite (GITOODO_SATELLITE=1) asks the service, which forwards it on the main host's subscription; the main host posts and confirms, then the worker is parked.
Remote worker lifecycle#
- The satellite records workers that end on their own and measures output silence. The main host
polls with
report(exits are drained, so each is delivered once) and applies the same hang policy as for local workers: silence for the timeout restarts the worker (aspawnwithoutprepare, in the worktree that already exists there), after the maximum it isstalled. reportalso carries the satellite's own subscription usage. The satellite starts reading it (keychain, usage endpoint,codex app-server) with the firstreport, not at service start, so a satellite no main host talks to stays idle and small (#769).- A worker that exits on its own is handled like a local one (finish/merge flow). A worker killed by the main host leaves no exit record.
- A run the main host tracks is not released as vanished for 45 s after start, so a slow poll cannot drop a fresh worker. Unreachable satellites keep the lease grace rules above.
- Run state of remote workers lives in memory only; after a dispatcher restart the lease table and the satellite's worker list decide (listed: renewed, not listed: released).
- Worktrees on the satellite carry the ownership marker;
hygiene_scanandhygiene_applylet the main host clean them up, and the satellite runs its own safe round (see repo hygiene).
Install and upgrade: gitoodo host install <name>#
Uses the system ssh/scp only (BatchMode, no stored secrets). Steps: uname -sm must match
this build's OS and CPU, upload to .local/bin/gitoodo.upload, compare the SHA-256 computed on the
satellite with the local one, only then move it over .local/bin/gitoodo, and finish with a
handshake. A mismatch deletes the upload and leaves the installed binary untouched. On a version
mismatch host add points to this command as the upgrade.
Version check and other systems in the app (#441)#
host_version runs one command on the machine (uname -sm and gitoodo --version, from PATH
or ~/.local/bin) and reports same, missing or other plus where an install comes from
(crates/core/src/remote_version.rs):
this_build: same system and processor, the app copies its own CLI as above.release: another supported system (macOS on Apple silicon, Linux x86_64/aarch64). The app downloads{base}/v{version}/gitoodo-{triple}andgitoodo-{triple}.sha256in Rust (size capped, no tokens), compares the SHA-256 before anything is copied and then uses the same verified upload.baseisGITOODO_RELEASE_URLat build time, by default the GitHub releases download URL. The release pipeline must publish both assets per target triple.intel_mac: a Mac with an Intel processor. Gitoodo for macOS runs on Apple silicon only (docs/release.md), so the assistant explains that and offers no install;updaterefuses withno_buildwithout downloading. The system isuname -sm, corrected toDarwin arm64viasysctl hw.optional.arm64when the login shell runs under Rosetta.none: no build for that system; the errorno_buildnames the system and asks to build Gitoodo there and place it at~/.local/bin/gitoodo. A missing asset (404) is alsono_build, any other download failuredownload_failed.
The "Add remote machine" assistant runs the check after connecting and offers install or update as its own step, which the user can skip; the machine list offers "Update all" for every machine whose probe reports another version, e.g. after an app update.
Machine suggestions and network search (#440)#
The address step of the assistant lists machines the user probably means
(crates/core/src/discovery, Tauri commands discovery_known, discovery_search,
discovery_cancel in src-tauri/src/discovery.rs):
- Right away, without network: hosts from
~/.ssh/config(withInclude, globs and paths relative to~/.ssh;HostName,Port,User,IdentityFile; wildcard patterns skipped) and plain entries fromknown_hosts. Hashedknown_hostsentries only mark a suggestion as "connected before", they never add one. - Only after "Search network": TCP port 22 on every address of the local subnets, derived from
the interfaces and capped at /24 (at most 254 addresses per interface; loopback, link-local and
public addresses skipped), with at most 64 probes at once, 500 ms connect and 1.5 s banner
timeout; a hit must answer with an
SSH-banner. In parallel the search listens 3 s for mDNS_ssh._tcpand_sftp-ssh._tcpannouncements. Progress reaches the page through a channel; "Stop search" sets a cancel flag, no new probe starts and the result so far is kept. - Suggestions are merged by address and port, keep every source (SSH config, network, connected before) and are marked "already added" when a saved machine uses that host. Picking one fills name, address, port and user of the manual entry; nothing is saved before the usual steps.
No token on the satellite#
The satellite has no account configuration and never reads the keychain; its config folder stays
empty. Questions reach the forge only through the main host (ask forwarding). Proven in
crates/cli/tests/satellite_bridge.rs.
App: Settings → Satellite hosts (#357)#
The page calls the same core functions as the CLI (crates/core/src/satellite_host.rs: probe,
install) through the Tauri commands hosts_list, host_probe, host_add, host_install and
host_remove (src-tauri/src/hosts.rs); the frontend never runs ssh itself.
- Every host is checked when the page opens, per row or all at once. A probe always returns a
state (
online,version_mismatch,unreachable,protocol); an offline host is not an error. - Adding saves the host only when it answers online with this version, optionally after a first install. Remove only drops the entry; nothing changes on the host.
- Failures carry a stable
reason(CmdError::Host), e.g.invalid_name,duplicate,unreachable,platform_mismatch,checksum_mismatch; the page shows a translated title and the technical text under details. - The store build cannot run
ssh:hosts_listreportssupported: falseand the page shows a hint to the direct build.