ssh_spawn
Run shell commands on a remote host in the background, get an instant job ID, and stream output line-by-line via ssh_tail. Ideal for builds, deploys, and log tails requiring real-time monitoring.
Instructions
Start a shell command on the remote host IN THE BACKGROUND and return a short job_id immediately (<100 ms). Use ssh_tail to stream output line-by-line while the job runs.
WHEN TO USE ssh_spawn:
You need real-time output in chat (builds, deploys, log tails).
The command takes more than ~60s but you WILL stay connected.
WARNING — PROCESS DIES ON DISCONNECT: ssh_spawn ties the remote process to the MCP server's SSH channel. If the MCP server restarts, Zed closes, or the connection drops — the remote process receives SIGHUP and dies. Do NOT use ssh_spawn for tasks that must survive a disconnect (multi-hour training runs, overnight parsers, etc.).
FOR TASKS THAT MUST SURVIVE DISCONNECT — use ssh_exec with nohup or screen instead: ssh_exec('nohup python -u train.py > /tmp/train.log 2>&1 &') ssh_exec('screen -dmS myjob bash -c "python train.py"') Then check progress with: ssh_exec('tail -n 50 /tmp/train.log') ssh_exec('screen -r myjob')
BUFFERING GOTCHA: many programs block-buffer stdout when stdin is not a TTY, so you see nothing until exit. Fix: pass pty=True, or use 'python -u' / PYTHONUNBUFFERED=1 / 'stdbuf -oL'. pty=True merges stderr into stdout.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The shell fragment to run on the remote. Passed to an outer ``bash -c`` with a PID-capture prelude, then ``exec``'d into an inner ``bash -c "<command>"`` so your shell metacharacters (``|``, ``&&``, ``$VAR``, redirects) work normally. | |
| host | No | Alias of the configured host, or its raw address. If omitted, the server's default host is used. | |
| cwd | No | Remote working directory (``cd`` before running). | |
| env | No | Additional environment variables for the remote process. Names must match ``[A-Za-z_][A-Za-z0-9_]*`` (safe env name regex, enforced by the wrapper builder). | |
| pty | No | Allocate a remote pseudo-TTY. Needed for interactive programs (``sudo -S``, REPLs, ``passwd``) and for line-buffered output from programs that only flush to a TTY. Note: with pty=True the remote kernel merges stderr into stdout, and CRLF line endings may appear in the buffer (we strip the \r). | |
| label | No | Optional human-readable tag for ``ssh_list_jobs``. Useful when the LLM spawns several jobs on the same host and needs a memorable handle ("nightly-parser", "log-follow", …). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||