ssh_task_launch
Launch a command in the background and return its PID right away for long-running tasks like installs, backups, or downloads; check status or read log files anytime.
Instructions
Launch a command in the background and return its PID immediately, without waiting for it to complete.
Prefer this over ssh_cmd_run for commands that will take a long time or may be quiet for extended periods: package installs, container/image pulls, large downloads, backups, compilation. It avoids holding a blocking tool call open and the ambiguity of io_timeout - the PID it returns survives reconnects and can be checked anytime with ssh_task_status(pid), and stdout_log/stderr_log can be read with ssh_file_read while the task is still running.
Output is redirected to files (see stdout_log/stderr_log), not captured in memory - read the log files to see progress or final output.
Windows targets: the command runs under cmd.exe (CMD syntax); for PowerShell use powershell -NoProfile -Command "...".
On Linux/macOS the launch FAILS with an error (nothing is started) if a log file can't be created, or, with use_sudo, if sudo itself fails - so a returned PID always means the task was really started. With use_sudo, logs in a directory only root can write are created and written as root.
Returns:
{'command', 'pid', 'start_time', 'stdout_log', 'stderr_log'}. Both are the paths
the output really goes to on the remote host (read them with ssh_file_read), or
None for a stream that's discarded - both are None if log_output=False, and
stdout_log is None if you passed only stderr_log. With neither passed, the
default is /tmp/task-<pid>.log on Linux/macOS (both streams in one file), and
C:\Windows\Temp\task-<pid>.log plus task-<pid>_err.log on Windows.
Long-running calls: if this takes longer than the server's wait cap (default 50s), it
returns {"status": "in_progress", "handle_id": ...} instead of the result - the work keeps
running. Get the result by polling ssh_cmd_check_status(handle_id=...), which returns this
tool's normal response once finished. Do not call it again meanwhile. Only one such
operation runs at a time; another one started meanwhile fails with a 'busy' error.Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Command to execute in the background | |
| use_sudo | No | Run command with sudo | |
| log_output | No | Whether to log output to files | |
| stderr_log | No | Path to redirect stderr (default: same file as stdout on Linux/macOS; a sibling <name>_err.log on Windows). The response's stderr_log always gives the real path. | |
| stdout_log | No | Path to redirect stdout (default: /tmp/task-<pid>.log on Linux/macOS, C:\Windows\Temp\task-<pid>.log on Windows) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||