chipi/agentic-ai-homelab/host-run

host-run

Inline commands over ssh break in ways that look like real failures:

• zsh on the laptop expands =word (echo ===== → zsh: ==== not found);
• nested quotes corrupt JSON bodies silently (Invalid JSON);
• inline Python f-strings can't contain backslashes;
• non-interactive shells on the mini lack /usr/local/bin, so docker isn't found.

All of these hit this repo's sessions repeatedly (2026-10-16/17). A script file has none of them.

Run

# write the commands to a file in your scratchpad, then:
~/.claude/skills/host-run/scripts/run.sh <host> <file.sh|file.py> [args...]

• .py files run with python3, anything else with bash.
• /usr/local/bin and /opt/homebrew/bin are put on PATH, so docker works on the mini.
• Arguments are passed literally (each one %q-quoted).
• The exit status is the remote script's: 2 means bad usage, 3 means the host is unreachable.
• The remote copy lives in /tmp/host-run.XXXXXX (mode 700) and is removed on exit.

Rules

• Secrets never go in the file or the arguments. The script loads them on the host

(set -a; . ~/…/.env; set +a), the way the handbook's recipes do.

• Read-only by default. A script that writes (deletes, restarts, mints) needs the same approval

as running those commands by hand.

• Keep the file in your scratchpad, not in a repo.

Verified

2026-10-17 on homelab and dgx:

• arguments "arg one" '$HOME' '=x' arrived literally;
• JSON with spaces round-tripped;
• echo ===== printed;
• an f-string with a backslash ran;
• docker resolved;
• exit 7 came back as 7, and an unknown host exited 2;
• no /tmp/host-run.* files were left on either host.

Not covered

• Interactive commands (sudo with a password, TUI tools).
• Copying files back; use scp for that.
• Long-running jobs; the script runs in the foreground of the ssh session.