workhorse-remote-access

name	workhorse-remote-access
description	Use when the user wants remote shell access or ad-hoc command execution through `cargo work`, including raw `cargo work -- ...` commands, stdin script execution with `cargo work exec`, `cargo work ssh`, port forwarding with `-L` or `-R`, environment injection, PTY allocation, shell selection, and reverse proxy setup with `-x` or `--all-proxy`.

Workhorse Remote Access

Overview

This skill covers interactive access and one-off remote execution against a horsed server. Use it when the task is not a standard Cargo workflow and needs a shell, a custom command, stdin-delivered script, forwarded ports, or proxy plumbing.

Preconditions

• Resolve target repo and host the same way as other cargo-work commands: --repo-name, --repo, or Git remote horsed; host from HORSED, --repo, or Git remote horsed.
• If the command is interactive, prefer PTY-backed execution.
• If the user just needs Cargo subcommands like build or test, use $workhorse-remote-build instead.

Command Patterns

For raw command execution:

cargo work -- ls -al
cargo work --repo ssh://git@127.0.0.1:2222/uuhan/workhorse.git -- uname -a
cargo work -t -- htop

For AI-agent or heredoc script execution:

cargo work exec <<'EOF'
set -euo pipefail
printf '%s\n' '{"name":"demo app","ok":true}'
pnpm --version
EOF

For interactive shell access:

cargo work ssh
cargo work ssh bash
cargo work --shell nu -- ls

For forwarding and proxying:

cargo work ssh -L 3000:127.0.0.1:3000
cargo work ssh -R 8080:127.0.0.1:8080
ALL_PROXY=socks5://127.0.0.1:1080 cargo work -x -- curl -I https://example.com

Decision Rules

1. Use cargo work -- <cmd> for short one-shot remote commands.
2. Use cargo work exec when the command is a multi-line script, contains JSON/headers/quotes/parens, or is generated by an agent and would otherwise need shell-layer escaping.
3. Use cargo work ssh when the user wants an interactive shell or port forwarding.
4. Use -t when the command expects a terminal UI or interactive input.
5. Use --env KEY=VALUE for small environment overrides.
6. Use --shell or HORSED_SHELL when the default interpreter is wrong for the remote platform.
7. Use -x when the server should route outbound traffic through the local proxy. Use --all-proxy=... when the proxy URL should be explicit.

Notes

• cargo work ssh defaults to an interactive shell on the server when no command is provided.
• cargo work exec reads the whole script from stdin, transports it as base64, and evaluates the decoded script with the selected remote shell. It is best for bash/zsh/sh-style hosts with base64 -d available.
• cargo work exec rejects empty stdin. Use a quoted heredoc delimiter such as <<'EOF' so the local shell does not expand the script before it is sent.
• For cmd / exec remote execution, horsed starts bash/zsh as interactive (-ic) so .bashrc / .zshrc PATH entries such as nvm, pnpm, fnm, and cargo shims are available by default. zsh does not need -lic for .zshrc; other shells keep plain -c.
• Reverse proxy mode picks a random remote port and exports ALL_PROXY, HTTP_PROXY, and HTTPS_PROXY back into the remote environment.
• If -x is set without local ALL_PROXY or all_proxy, the command warns and continues without proxy setup.

Examples

# Start an interactive shell on the default server
cargo work ssh

# Run a command with extra env
cargo work --env RUST_LOG=debug -- printenv RUST_LOG

# Run an agent-generated script without nested quoting
cargo work exec <<'EOF'
set -euo pipefail
curl -H 'Content-Type: application/json' -d '{"ok":true}' https://example.com/hook
EOF

# Forward local 3000 to the remote app
cargo work ssh -L 3000:127.0.0.1:3000

# Publish a local service through the server
cargo work ssh -R 8080:127.0.0.1:8080