API Reference

Five functions cover almost every SSH script. Every call returns decoded strings and real exit codes — never raw bytes, never a forgotten recv_exit_status().

Install & import

pip install remote-run-llm

from remote_run import run, upload, download, run_many, run_script, CommandResult

run(host, command, ...) → CommandResult

Run a command on a remote host over SSH.

result = run(
    "203.0.113.10",
    "df -h",
    user="ubuntu",
    key="~/.ssh/id_ed25519",
    password=None,           # login password
    key_passphrase=None,     # encrypted key passphrase
    port=22,
    connect_timeout=30,
    command_timeout=300,
)

CommandResult

Field	Type	Description
`stdout`	str	Decoded standard output
`stderr`	str	Decoded standard error
`exit_code`	int	Remote command exit status
`.ok`	bool	`exit_code == 0`
`.failed`	bool	`exit_code != 0`
`host`	str	Host that was connected to
`command`	str	Command that was executed

upload(host, local_path, remote_path, ...) → None

Upload a local file to a remote path over SFTP — no open_sftp() ceremony.

upload("203.0.113.10", "dist/app.zip", "/var/www/app.zip", user="deploy")

download(host, remote_path, local_path, ...) → None

Download a remote file to a local path over SFTP.

download("203.0.113.10", "/var/log/nginx/error.log", "./error.log")

run_script(host, local_path, *args, ...) → CommandResult

Upload a local script and run it on a remote host in one SSH session. Edits stay on your machine — the file is copied to /tmp/remote-run-llm/, executed, and removed by default.

result = run_script(
    "192.168.1.101",
    "hello.py",
    user="ubuntu",
    key="~/.ssh/id_ed25519",
)

# Script arguments go after the path
result = run_script("vm.local", "deploy.sh", "--dry-run", user="deploy")

# Override interpreter or keep the remote copy for debugging
result = run_script("vm.local", "task.pl", interpreter="perl", cleanup=False)

Auto-selects python3 for .py, bash for .sh, or honors a #! shebang. For multi-file scripts, upload dependencies separately or deploy the project directory.

run_many(hosts, command, ...) → dict[str, CommandResult]

Run the same command across many hosts in parallel.

results = run_many(["web1", "web2", "web3"], "uptime", user="root")
for host, result in results.items():
    print(host, result.stdout if result.ok else result.stderr)

Environment variables

Variable	Purpose
`SSH_HOST`	Default host (`run(None, ...)`)
`SSH_USER`	Username
`SSH_KEY`	Private key path
`SSH_PASSWORD`	Login password
`SSH_KEY_PASSPHRASE`	Encrypted key passphrase
`SSH_STRICT=1`	Strict host-key checking

Opinionated defaults

Auto-detect Ed25519, RSA, ECDSA private keys
AutoAddPolicy for host keys (unless SSH_STRICT=1)
Disable agent + look_for_keys when explicit key is passed
Connections always closed automatically
Actionable errors for auth and passphrase failures