Awaitless
OfficialThis server provides tools for submitting, monitoring, and managing durable background jobs across local, SSH, and Slurm backends, freeing agents from continuous polling.
Submit jobs: Use
submit_jobto launch a durable command and get a stable job ID immediately. Supports deduplication viaclient_request_id, optional queues, environment variables, working directory, artifacts, timeouts, and Slurm-specific options. Userun_jobfor a one-call submit-and-track: tasks-aware clients receive a durable Task handle; older clients block until completion.Wait for completion:
wait_for_jobblocks until a job finishes, returning final state, exit code, bounded logs, and any collected artifacts. Reconnectable by job ID across sessions.Check status:
get_job_statusretrieves the current durable state (queued, running, succeeded, failed) instantly.Retrieve logs:
get_job_logsreturns bounded stdout/stderr tails with configurable tail length or max bytes to avoid flooding context.Cancel jobs:
cancel_jobcancels a running or queued job with a configurable grace period for clean shutdown.List jobs:
list_jobslists recent jobs, filterable by state or host, with a configurable limit.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Awaitless Start the training job and send me the job ID when it's ready"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Awaitless
Adaptive durable execution for coding agents.
Run commands through one execution layer. Quick work returns inline; longer or queued work becomes durable across local, SSH, and Slurm. Your workload stays on infrastructure you already own.
Agents submit work. Awaitless owns execution.
Awaitless is the adaptive durable execution layer between coding agents and the compute they use. It gives agents one stable job contract while reusing your local machine, SSH hosts, and Slurm clusters underneath.
简体中文 · Documentation · Benchmarks · PyPI
One job lifecycle across your existing compute
Coding agent → submit work → Awaitless owns the job lifecycle → Local / SSH / SlurmDurable jobs | Named scarce-resource queues | Completion and recovery |
Stable IDs, state, cancellation, bounded logs, and Artifacts survive client disconnects. | Durable FIFO admission prevents too many jobs from entering a named resource at once. | Exit codes and results remain available by Job ID or replayable completion cursor. |
Awaitless owns the job lifecycle, not the hardware. It does not discover
resources, understand GPU topology, allocate multiple resources, or replace a
cluster scheduler. Operators name queues and set fixed concurrency; Slurm
continues to handle requests such as --gpus 2 --mem 64G and all physical
cluster scheduling.

Related MCP server: script-runner
Your coding agent should write code, not babysit jobs
An agent can write its own run → sleep → check loop. The harder problem is
making job identity, disconnect recovery, queue admission, cancellation, and
result delivery reliable across long workloads and changing sessions. Without
that execution layer, the agent repeatedly pulls the same growing log back into
its context:
ssh gpu 'run_benchmark > job.log 2>&1 &'
ssh gpu 'tail -n 200 job.log' # again...
ssh gpu 'tail -n 200 job.log' # and again...Awaitless turns that lifecycle into one adaptive execution call and one result boundary:
awaitless run --json --host gpu --artifact results.json -- ./run_benchmark
# quick: {"state":"succeeded","delivery":"inline","exit_code":0,...}
# longer: {"job_id":"job_019F...","state":"running","delivery":"detached",...}
awaitless wait job_019F... --json
# {"state":"succeeded","exit_code":0,"parsed_results":{...}}Detached JSON also includes job_state, wait_state, delivery_state, and a
ready-to-copy next_command. A client-side wait timeout is not a workload
failure: use awaitless wait --last --json for the most recently detached Job,
or use the returned command with its stable Job ID. To inspect benchmark lines
without reading a large tail, use awaitless logs <job-id> --grep 'PASS|FAIL|median|CV'.
Every run is durable before launch. Finishing within the inline window looks
like an ordinary command result; crossing it only detaches the waiter. Interrupt
the waiter, close the MCP client, or start a fresh agent session: the Job keeps
running and its stable ID recovers the result.
Queue work before a named resource is free
Create a durable FIFO queue once, then submit every command immediately:
awaitless queue create gpu0 --concurrency 1
awaitless submit --queue gpu0 -- python train_a.py
awaitless submit --queue gpu0 -- python train_b.py
awaitless submit --queue gpu0 -- python train_c.pyThe first command runs and the others report queued. Each starts automatically
when capacity becomes available. This is durable admission control for a named
scarce resource: fixed concurrency and FIFO ordering, with no priority or
preemption. Awaitless never kills running work to make room for a later job.
Operators can also bind adaptive runs to a queue globally or per host:
[hosts.gpu]
hostname = "gpu.example.com"
queue = "gpu0"The Agent can then call run without choosing a queue or probing the GPU first.
This queue does not discover resources, understand GPU topology, dynamically allocate devices, issue leases, or combine requests such as two GPUs plus 64 GB of memory. Use Slurm or another scheduler for those responsibilities; Awaitless provides the Agent-facing job lifecycle around that scheduler.
Consume whichever job finishes next
v0.7 adds completions ... --drain --json for consuming a small parallel set
in one call without client-side cursor bookkeeping. Long jobs can emit
structured heartbeat updates with wait --progress-interval 30s. Use
--capture-log PATH for command-owned logs and --resource gpu=0 or
--device 0 for explicit exclusive admission; terminal results freeze bounded
logs, diagnostics, timing, environment, and a SHA-256 identified snapshot.
Submit independent work up front, keep every Job ID, then wait at one durable completion boundary:
awaitless completions job_A job_B job_C --json
# {"completions":[...],"next_cursor":"cmp_...","active_job_ids":[...]}
awaitless completions job_A job_B job_C --after cmp_... --jsonThe first call returns already-finished work immediately or blocks until at
least one selected Job completes. Process the batch before advancing to
next_cursor; reusing an older cursor safely replays the same completion IDs.
If the client disappears, a new session can continue from the saved cursor.
Awaitless makes continuation results durably available—it does not run the
agent's next reasoning step or require a resident notification service.
The v0.8 evidence suite replaces historical call-count demos with four
questions: does an Agent choose the protocol correctly, does a Job survive
faults without duplicate launch, does Awaitless keep execution-management state
out of the reasoning loop, and does adaptive run preserve low friction for
short commands? See the v0.8 evidence plan.
v0.8 evidence status
Release evidence is model- and commit-specific. The checked-in suite does not carry numbers from earlier versions or from a different model. Run the v0.8 benchmarks, inspect every raw record, then publish a dated report with model, config hash, git commit, skipped workloads, and all failures in the denominator. The reviewed v0.8 evidence report includes the complete raw records and analysis summaries rather than a selected score.
Try the recovery story in 30 seconds
Linux, Python 3.10+, and Bash are required. Run the built-in demo without a persistent install:
uvx --from awaitless-runner awaitless demo --jsonThe demo submits two local jobs, terminates their first completion waiter, then uses new clients to consume both bounded results and JSON Artifacts by cursor.
For regular CLI use:
uv tool install awaitless-runner
awaitless doctor --jsonpip install awaitless-runner works too.
Give it to your coding agent
Add one stdio MCP server to your client's configuration (adapt the outer key to your client):
{
"mcpServers": {
"awaitless": {
"command": "uvx",
"args": ["awaitless-runner"]
}
}
}The preferred run tool returns quick commands inline and automatically gives
longer or queued work a durable handle. Tasks-aware clients can still use
run_job, while low-level clients retain submit_job and wait_for_job.
Retrying an expensive submission with the same
client_request_id cannot launch a duplicate job. For parallel work, every
client can use wait_for_completions regardless of MCP Tasks support.
The normative identity, lifecycle, continuation, completion, Artifact, and
compatibility contract is Awaitless Agent Job Protocol.
Codex plugin
This repository is also a Codex plugin. Its manifest bundles the Awaitless agent
skill with the stdio MCP server, which Codex launches through uvx. Install the
repository from a local Codex marketplace, then start a new Codex task so the
skill and MCP tools are loaded together.
The plugin requires uvx on PATH; the first MCP launch downloads
awaitless-runner from PyPI if it is not already cached.
For direct CLI use, the whole loop is:
awaitless run --json --name tests -- python -m pytest -q
# If delivery is detached, save the returned job_id, then:
awaitless wait <job-id> --json
# Or recover the most recent detached job:
awaitless wait --last --jsonOne interface, three places to run
Backend | What Awaitless adds |
Local | Durable process-group tracking, cancellation, bounded logs, and transactional named queues. |
SSH | The same job contract plus queues coordinated on the target host, with no remote daemon. |
Slurm | Real |
Use --backend, --host, or configuration defaults to switch targets without
changing how the agent submits and collects work.
Why not just use a shell or tmux?
Tool | Best at | What the agent still has to build |
Blocking shell call | Quick inspection and interactive work | Lifecycle management once an engineering command runs longer than expected. |
Shell polling / | Keeping a basic command alive | IDs, status, exit-code recovery, bounded logs, cancellation, deduplication, and result parsing. |
| Humans detaching from interactive shells, REPLs, and TUIs | A reliable non-interactive job protocol and wrapper glue. |
Awaitless | Agent-run builds, tests, benchmarks, remote jobs, and cluster work | Only the command and, optionally, the JSON Artifact to return. |
Awaitless does not replace interactive terminals or Slurm. It gives coding agents durable fixed-concurrency queues on local/SSH machines and delegates cluster resource scheduling to Slurm.
How it works
flowchart LR
A["Coding agent"] -->|"run"| B["Awaitless MCP / CLI"]
B --> C[("SQLite job record")]
C --> Q["Optional queue admission"]
Q -->|"capacity available"| D{"Backend"}
D --> L["Local process"]
D --> S["SSH host"]
D --> H["Slurm allocation"]
L --> I{"Finished inline?"}
S --> I
H --> I
I -->|"yes: result"| A
I -->|"no: durable handle"| A
A -. "reconnect with stable ID" .-> C
C --> E["Durable completion cursor"]
E -->|"state + exit code + bounded logs + Artifacts"| AThere is no Awaitless daemon, HTTP service, or hosted sandbox. Each invocation opens the same SQLite store; submitted runners and scheduler jobs outlive the stdio server that created them. Full logs remain on disk while only bounded tails enter the agent context.
Documentation
License
Available Tools
11 toolscancel_jobA
Cancel a durable job without relying on a client-side process handle.
Inputs: job_id (required), grace_seconds. Returns: object
create_queueA
Create an immutable named FIFO queue with a fixed concurrency limit.
Inputs: name (required), concurrency (required). Returns: object
get_job_logsA
Inspect bounded stdout and stderr tails for a known failed or stalled job.
Use after a terminal wait reports failure, timeout, stall, or loss and its bounded result needs focused diagnostics. Do not use as a progress stream, do not repeatedly tail a running healthy Job, and do not use it instead of wait_for_job to learn that work completed.
Inputs: job_id (required), tail, max_bytes. Returns: object
get_job_statusA
Get one immediate, non-waiting state snapshot for a known job_id.
Use only when the caller needs current status now. Do not use this to wait for completion or build a polling loop; use wait_for_job for one Job or wait_for_completions for several. This tool never starts or retries work.
Inputs: job_id (required). Returns: object
list_jobsB
List recent durable jobs, optionally filtered by state or host.
Inputs: host, limit, queue, state. Returns: object
list_queuesA
List named queues and their current queued/active job counts.
Inputs: no named parameters. Returns: object
runA
Default tool for starting one non-interactive command of uncertain duration.
Every command is a durable Job from launch. Commands that finish within the inline timeout return their ordinary bounded result. Longer or queued work returns a detached Job handle without cancelling the workload. Omit queue to use an operator-configured default queue for the selected target.
Do not use this tool for explicit fire-and-forget or batch fan-out; use submit_job. Do not use it when an MCP Tasks handle is explicitly required; use run_job. Do not use it to resume an existing job_id; wait for or inspect that job instead. If a detached handle is returned, keep its job_id and call wait_for_job once when the result is needed rather than polling status.
Inputs: command (required), cwd, env, host, +11 more. Returns: object
run_jobA
MCP Tasks compatibility entry point for explicitly creating a Task handle.
A client declaring io.modelcontextprotocol/tasks receives a Task handle immediately. Older clients block and receive the ordinary final tool result. The stable client_request_id makes a lost creation response safe to retry.
Do not choose this for ordinary command execution: use run. Do not choose it for generic asynchronous submission or fan-out: use submit_job. Only retry a lost Task creation with the same client_request_id and identical arguments.
Inputs: command (required), client_request_id (required), cwd, env, +10 more. Returns: object
submit_jobA
Explicitly submit one asynchronous or fan-out job without waiting.
Omitted backend and host values use the Awaitless configuration defaults. Reuse client_request_id only when retrying the same logical submission; an identical retry returns the original job and a conflicting retry is rejected. A named queue provides FIFO, non-preemptive admission for local or SSH work. Slurm options may contain account, constraint, cpus_per_task, gres, mem, nodes, ntasks, partition, qos, or time. Cluster config supplies defaults.
Do not use this as the default for a single command with uncertain duration; use run. Do not use it for MCP Tasks creation; use run_job. Do not resubmit merely because a client disconnected or a wait timed out: keep the original job_id, or retry the identical logical submission with the same client_request_id if the creation response was lost.
Inputs: command (required), cwd, env, host, +10 more. Returns: object
wait_for_completionsA
Collect durable terminal results across multiple known jobs after a cursor.
Existing completions return immediately. Otherwise the call waits until at least one selected job completes or the optional call-level timeout expires. Reusing the same cursor replays results; advancing to next_cursor consumes the returned batch. A timeout never cancels a managed job.
Submit all independent jobs before calling this tool. Treat delivery as at-least-once: process and deduplicate by completion_id before advancing the cursor. Do not use this for one job, do not poll get_job_status between continuation calls, and never resubmit active jobs after a waiter disconnects.
Inputs: job_ids (required), limit, after_cursor, timeout_seconds. Returns: object
wait_for_jobA
Wait once for a known job_id and consume its durable terminal result.
Returns state, exit code, bounded logs, and declared Artifacts. A client-side timeout or disconnect does not cancel the Job; call this tool again later with the same job_id. Do not use it to start work, do not poll it repeatedly, and use wait_for_completions instead when collecting several independent Jobs.
Inputs: job_id (required), timeout_seconds. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose: run for default single command, submit_job for async/fan-out, run_job for MCP Tasks compatibility, wait_for_job for single job waiting, wait_for_completions for multiple jobs, get_job_status for snapshots, get_job_logs for diagnostics, plus cancel/list/queue tools. Descriptions explicitly cross-reference when not to use each, eliminating ambiguity.
All 11 tools follow a consistent verb_noun snake_case pattern (run, submit_job, wait_for_job, wait_for_completions, get_job_status, get_job_logs, cancel_job, list_jobs, create_queue, list_queues). No style mixing or vague verbs.
11 tools cover the job lifecycle and queue management without excess. Each tool has a clear role, and the count is appropriate for a job orchestration server—neither too thin nor bloated.
The surface covers the full lifecycle: creation (run, submit_job, run_job), waiting and collection (wait_for_job, wait_for_completions), status (get_job_status), logs (get_job_logs), cancel (cancel_job), listing (list_jobs), and queue management (create_queue, list_queues). No obvious gaps for the domain.
Maintenance
Related MCP Connectors
Hosted MCP server for task-first delegation to remote workstations and workers.
Remote MCP server for notes, tasks, kanban boards and docs - the Slates agentic workspace
MCP server for Superserve sandboxes: create, exec, and manage Firecracker microVMs
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA lightweight, cross-platform MCP server for managing background processes. Enables AI coding agents to spawn, monitor, and interact with long-lived processes.MIT
- FlicenseNot gradedqualityBmaintenanceRemote MCP server that launches user-supplied scripts inside disposable Docker containers, returning task IDs for async tracking and bounded output tails.-
- AlicenseNot gradedqualityBmaintenanceA command execution MCP server supporting local execution, sandbox isolation via Docker/OpenSandbox, and SSH remote execution.MIT
- AlicenseAqualityCmaintenanceMCP server that enables running and managing file-based AI Skills, Agents, and Flow workflows as DAGs, with tools for listing, executing, and resuming tasks via stdio JSON-RPC.9MIT