User Guide
Command reference. For a hands-on path, use First Steps (Requirements → Prepare → First job).
Full help: julia --project=. -m DistSSHKitQueue --help. Each command page starts with a Flags table for that command. Kit go / drive / size flags stay in the kit User Guide.
| submit | Enqueue DistSSHKit go / drive |
| status | status / watch / cancel |
| hosts | add-host / remove-host / list-host / size |
| waiter | serve / stop / enable / disable |
| setup | setup / teardown / config.toml |
Client vs queue host
qhost:HOST is a client token (like Kit child:NAME). On the queue host, omit it.
Refuse qhost:: setup, serve, enable, disable, add-host, remove-host. Forward: submit, status, list-host, size, watch, cancel, stop, teardown.
--hosts / --julia belong to Kit go / drive. Queue-host Julia is --remote-julia / JULIA_DISTRIBUTED_EXE. Default hop: DISTSSHKITQUEUE_HOST (not DISTSSHKIT_HOSTS). Not forwarded. Not DISTSSHKITQUEUE_QHOST (that is status / watch display).
serve is “run the process”. enable is “register that process with the OS” (LaunchAgent / systemd). enable does not make a laptop a queue host. disable is the opposite of enable, not of serve.
Job record
Each row: id (UUID), kind (:go / :drive), script, hosts, state (:queued / :running / :done / :failed / :cancelled), queued_at / started_at / finished_at, error, and result_path — Kit's output directory. If submit omitted --output-dir, the waiter sets one with DistSSHKit allocate_output_dir when the row becomes :running (so cancel and a later serve can find kit.pid). Queue does not keep a second copy of Kit's result tree. Kit kwargs (args, project, output_dir, …) travel as an opaque bag through DistSSHKit's execute! allow-list. The waiter also passes job_id (the row UUID) so Kit progress lines can carry job=.
The table is TOML on the queue host (~/.distsshkitqueue/jobs.toml), rewritten under a directory lock. If the waiter dies: :queued rows reload on the next serve. A :running row whose DistSSHKit kit.pid is still alive stays :running (the waiter will not start the next FIFO job). A :running row with no live kit.pid is :done or :failed from kit.result when that file exists, otherwise :failed.
Shared peel
| Topic | Rule |
|---|---|
-q / --quiet | status / watch: table only. Kit DISTSSHKIT_QUIET. |
--progress / --verbose | Accepted (exclusive with -q); Queue has no live Kit run, so they keep chrome. |
-v / --version | Top-level: Queue then DistSSHKit. submit go -v is Kit only. |
-y / --yes | teardown (or DISTSSHKIT_YES). Same values as DistSSHKit. |
| Ctrl-C | serve / watch: that process only, never a running Kit job. |
Out of scope
A scheduler inside DistSSHKit, weakdeps from Queue to DistSSHKit, a glue package, lab-wide slot ceilings or occupancy packing, preemption / fair-share / priorities / reservations / backfill, HTTP or a listen socket, a sleeping laptop as the waiter, auto-retry of crashed :running jobs, a Queue-owned copy of Kit's result trees, and native Windows.