jobd_submit
Submit shell commands to a job broker for queued execution on workers. Supports async or synchronous blocking mode with optional GPU pinning.
Instructions
Submit a job to the jobd broker. Default async; pass wait=true to block up to wait_timeout_s (server clamps to 270).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path; broker validates against worker mount_roots. | |
| gpu | No | Pin to GPU-capable worker. | |
| host | No | Host alias pin (laptop, desktop-vm). | |
| wait | No | Sync mode: block until terminal or timeout. For an array submit (count/sweep), waits on every member under one shared deadline and returns an aggregate {array_id, count, job_ids, states, all_completed, members:[{job_id, state, exit_code}]}. | |
| extra | No | Escape hatch: idempotent (bool), depends_on (int[]), depends_on_any_exit (bool), priority (int delta), max_wall_s (int), idle_timeout_s (int), scheduling_timeout_s (int 1..604800 — give up and terminate the job as 'scheduling_timeout' if it is still QUEUED after N seconds; omit to wait indefinitely for a capable worker), checkpoint_grace_s (int 1..300), vram_gb (float — explicit GPU VRAM the job needs at dispatch; falls back to cuda-Ngb tier-tag max, then to 2 GB floor for --gpu jobs), count (int 1..1000 — submit a job array of N members, with `{i}` in the command replaced by the 0-based index; response is {array_id, count, job_ids, warnings} instead of a single job), sweep (list of {key, values[]} — parameter-sweep axes; broker fans out the cartesian product, substituting `{key}` per member plus `{i}`; mutually exclusive with count; product capped at 1000), profile (str), env (dict), preemptible (bool), session_id (str), arch (str — pin to a worker CPU arch), os (str — pin to a worker OS). | |
| needs | No | Tool tags (R, python3, cuda). | |
| command | Yes | Shell command run by the worker shell. | |
| dry_run | No | Preview mode: run full validation + routing decision (profile, project defaults, cwd, depends_on, preflight, gpu_contention) and return the would-be plan WITHOUT queueing. Response has state='dry-run', would_route_to (list[host]), would_use_worker (host or null), validation (resolved fields + warnings). Per dry-run convention 2026-05-18. | |
| project | Yes | Priority lookup key; falls back to _default. | |
| wait_timeout_s | No | Seconds; permissive — server clamps to 270. |