Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Orchestrator

Satellites

On this page
  1. Pieces
  2. Remote worker lifecycle
  3. Install and upgrade: gitoodo host install <name>
  4. Version check and other systems in the app (#441)
  5. Machine suggestions and network search (#440)
  6. No token on the satellite
  7. App: Settings → Satellite hosts (#357)

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 on satellite.sock (0600) holding worker PTYs. gitoodo satellite --stdio is a pipe to that socket (it starts the service when missing), so workers survive SSH drops.
  • Protocol: JSON lines, the same cmd/reply/frame vocabulary as the dispatcher socket (dispatcher_rpc.rs), plus hello, spawn, kill, subscribe, ask, ask_done. A bridge session runs requests in a row; subscribe and attach turn it into a stream.
  • Bridge: system ssh -o BatchMode=yes ... -- <target> gitoodo satellite --stdio (GITOODO_SSH replaces 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 ask on 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 (a spawn without prepare, in the worktree that already exists there), after the maximum it is stalled.
  • report also carries the satellite's own subscription usage. The satellite starts reading it (keychain, usage endpoint, codex app-server) with the first report, 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_scan and hygiene_apply let 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} and gitoodo-{triple}.sha256 in Rust (size capped, no tokens), compares the SHA-256 before anything is copied and then uses the same verified upload. base is GITOODO_RELEASE_URL at 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; update refuses with no_build without downloading. The system is uname -sm, corrected to Darwin arm64 via sysctl hw.optional.arm64 when the login shell runs under Rosetta.
  • none: no build for that system; the error no_build names the system and asks to build Gitoodo there and place it at ~/.local/bin/gitoodo. A missing asset (404) is also no_build, any other download failure download_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 (with Include, globs and paths relative to ~/.ssh; HostName, Port, User, IdentityFile; wildcard patterns skipped) and plain entries from known_hosts. Hashed known_hosts entries 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._tcp and _sftp-ssh._tcp announcements. 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_list reports supported: false and the page shows a hint to the direct build.
Docs version: dev