Shell & file tools — local / remote / website / runpod

The host-scoped shell-execution and filesystem tool families — local_*, remote_*, website_*, runpod_*, and the Leif-workspace file tools — and which one targets which host.

Four near-identical tool families do shell execution and file I/O, each bound to a different host. The signatures barely differ; the target is the whole point. Pick the wrong family and you run against the wrong machine — the single most common wrong-tool bug. This page is the per-family reference; the authoritative target mapping is the Hosts routing table.

local_* — the Leif host

Shell and service control on the Leif host itself (10.10.0.25).

local_execute_command(command, timeout=10)
local_restart_service(service_name)
local_get_system_info()

local_restart_service is the only host-specific extra in the shell families — it restarts a systemd unit on the Leif host. Note the short 10s default timeout; bump timeout for anything slow.

remote_* — nvrbackup (via SSH)

Shell and file access on the configured SSH target — nvrbackup (10.10.0.14, SSH :2223). This is the family for the pricing app, the RS ticket sync, and anything else on that host outside the finance tree.

remote_execute_command(command, timeout=30)
remote_read_file(path)
remote_write_file(path, content)
remote_list_directory(path)
remote_file_exists(path)
remote_get_system_info()

remote_write_file with a heredoc-style payload is how CSVs get onto nvrbackup for imports — and /tmp/<file>.csv on nvrbackup is the path the importer can actually read.

website_* — the website host (sandboxed)

Shell and file access scoped to allowed website roots. Unlike the others, website_execute_command blocks cd and .. traversal — you operate within one root alias.

website_execute_command(command, root=None, timeout=30)
website_write_file(path, content)
website_read_file(path)
website_list_directory(path)
website_file_exists(path)
website_create_directory(path)
website_delete_file(path)
website_get_system_info()
website_list_roots()

Call website_list_roots() first to see the allowed root aliases; pass one as root to scope a command. Paths are relative to the configured site roots.

runpod_* — the RunPod GPU pod (ephemeral)

Shell and file access on the on-demand RunPod instance. The endpoint rotates per pod start, so a connection error usually means the pod is stopped, not that the tool is broken — see Hosts.

runpod_execute_command(command, timeout=60)
runpod_read_file(path)
runpod_write_file(path, content)
runpod_list_directory(path)
runpod_get_system_info()

Note the longer 60s default timeout — GPU work is slow to start.

Leif-workspace file tools (no host prefix)

The unprefixed file tools operate on the Leif workspace directory on the Leif host. Use these for scratch files and drafting; they are not a way to write to /tmp or to another host.

read_file(path)
write_file(path, content)        # create or overwrite
create_file(path, content)
delete_file(path)
list_directory(path=".")
create_directory(path)

For repository writes use the github_* tools (Files, code & web); for another host use that host’s family above.

Choosing the right family

Related pages

• Hosts — the authoritative host inventory and routing table
• Tools — catalog overview and the routing-rules table
• Pricing App File Import — the canonical “wrote to the wrong host” trap