submit

Enqueue a DistSSHKit go, ride, or drive. Starts serve if none is running. That serve instantiates the job project on the queue host and runs setup! on child: hosts before execute! (not a hand-run DistSSHKit setup on the stage tree). :check always runs on child: hosts (warns if a qhost: stage has no .git/).

Type the line on a client, in the job directory (Queue must be loadable; --project=. is that tree, and SCRIPT.jl lives there). Not already on the queue host: include qhost:HOST. Already logged in on that always-on machine? Same directory, omit qhost:. Do not type this on a worker. serve on the queue host runs the DistSSHKit argv later.

cd ~/my-job    # Project.toml, SCRIPT.jl; Queue loadable

# another machine (not the queue host)
julia --project=. -m DistSSHKit qhost:HOST submit drive parent:4 SCRIPT.jl

# already on the queue host
julia --project=. -m DistSSHKit submit drive parent:4 SCRIPT.jl

One argv, four nested pieces. qhost:HOST is the SSH name of that queue machine. submit is Queue. The next word is the DistSSHKit kind (go / ride / drive); after that, argv matches DistSSHKit.

julia --project=. -m DistSSHKit  [qhost:HOST]  submit  drive  parent:4  SCRIPT.jl
#──────────── Julia ────────────┘  └─ qhost ──┘  Queue   └─── DistSSHKit argv ────┘

julia --project=. -m DistSSHKit [qhost:HOST] submit drive parent:4 SCRIPT.jl

A long line in the terminal is still one command. Break after submit with \:

julia --project=. -m DistSSHKit [qhost:HOST] submit \
    drive parent:4 child:NAME:N SCRIPT.jl

The same argv, started on this machine now:

julia --project=. -m DistSSHKit drive parent:4 SCRIPT.jl

That starts compute on this machine, now. submit only enqueues the same argv; serve runs it later on the queue host (after qhost:, on the staged tree). Start the same argv on this machine to debug placement, then enqueue.

pool:N sits next to submit. It is not a host token: it expands config hosts to the same :N (clamped by add-host max). Place it next to submit (before or after the kind), not among parent / child tokens. Library submit! does not expand pool:N. Inspect pool (no enqueue) is User Guide · hosts.

julia --project=. -m DistSSHKit  [qhost:HOST]  submit  pool:8  drive  SCRIPT.jl
#──────────── Julia ────────────┘  └─ qhost ──┘  └─ submit ──┘  └─ go / ride / drive ─┘

A .jl with no queue verb is not implicit go (same as go / ride / drive on this machine). Top-level go / ride / drive are DistSSHKit; enqueue with submit. ride is experimental.

Also: First job, Walkthrough, hosts, julia -m DistSSHKit --help. Flags: go, ride, drive.

CLI submit uses Queue(; follow_config=true) so each enqueue re-reads config hosts. Library submit! uses Queue(; allowed=…) unless follow_config=true.

With qhost:, the client rsyncs the job project (cwd / DISTRIBUTED_PROJECT_ROOT) to ~/.distsshqueue/stage/<uuid> on the queue host, then enqueue resolves SCRIPT.jl there. In a git work tree the paths are the same as setup --rsync, then anything under .distsshqueue/ is dropped. .git/ and .distsshkit/ are already out of that list. A different name, such as .distsshqueue-backup, is not that directory and stays when the list includes it. Outside a git work tree there is no send list: rsync applies each directory's .gitignore and excludes .git/, .distsshkit/, and .distsshqueue/. The client keeps .distsshqueue/tickets/<uuid> (every qhost: submit from this tree; not an artifact). Artifacts and paths explains stage, ticket, the run's output, and the fetch destination. Omit qhost:: the script is checked on this machine. Job id prints as a bare stdout line. CLI submit also prints queue: local (HOSTNAME) (or qhost: local (HOSTNAME) on the hopped process when you passed qhost:) then Queued N (no running) on stderr ((R running) when a job is already running); DISTSSHKIT_QUIET hides that. A qhost: rsync prints rsync → HOST:… when it starts (fetch: rsync ←). DISTSSHKIT_PROGRESS / --progress adds rsync --info=progress2. Missing config hosts: a parent / child: token is an error (add-host first). hosts = [] allows none.

Two different projects that the run would deploy to the same worker path are refused (no rename, no setup --delete). The same project may be submitted again.

Flags

go / ride / drive argv is forwarded as-is. The extra on this line is pool:N (above). A drive row is :done when ok is true (listed hosts must join unless --best-effort).

Opt out of auto serve: DISTSSHQUEUE_NO_AUTOSERVE=1. A prior stop also holds serve off until an explicit serve.

A job that is already :running is not stopped when hosts changes. :queued rows still start if a name is later removed.