portal_exec

Run a shell command on one or more remote hosts over SSH and get the result immediately (exit code + SEPARATE stdout/stderr). This is the default way to execute ANYTHING on a remote machine — reach for it instead of hand-rolling ssh user@host …; it reuses a warm connection pool and fans out across hosts. Stateless: need cwd/exports to persist → portal_shell; a long task to background and poll → portal_job.

★ sudo: to run a command as root, call this with use_sudo=True — NEVER put a bare sudo … in the command or in portal_shell (there is no TTY and the password can't be fed). The password is supplied out-of-band; you never pass it. (For root on the server's OWN machine, sudo is not available — see portal_local_exec.)

★ credentials: when a command needs a secret (API token, deploy key, …), do NOT have the user paste it into the chat. They run portal secret set <name> in their own terminal; you pass secrets=[""] and reference it as the uppercased env var ($NAME).

Targets (pick one): host="web01" | host=["web01","web02"] | group_tag="prod" (all registered hosts carrying that tag).

Commands (pick one): command="uptime" (a single command; a multi-line string runs as one bash script) | commands=["apt update","apt upgrade"] (a sequence, each with its own exit code, stopping at the first failure when stop_on_error=True). Prefer the commands=[…] array over packing several lines into one string — it can't be silently flattened and you get per-step exit codes (matters most with use_sudo, where each entry runs as its own sudo command).

Multi-host fan-out is parallel by default; serialize=True (+ delay_s, stop_on_error) does a rolling, stop-on-first-failure rollout.

timeout (seconds, default 1h, operator-lowerable via PORTAL_DEFAULT_TIMEOUT): the call is held open until the command finishes or timeout elapses. Keepalive pings stop the client aborting a hung call, so timeout is your real cut-off — for an exploratory / re-runnable command pass a SMALL one first (e.g. 10–30) to fail fast, raising it only for commands you know are slow; keep it generous for ones whose mid-flight kill is dangerous (migrations, package upgrades).

use_sudo: run via sudo -S, with the password resolved out-of-band per host (the per-user credential agent from portal sudo set <host>, or the host's sudo_password_command) — never from you. Refused with guidance if no source is set. Consumes the command's stdin (tools that read their own stdin aren't supported under sudo). Cannot be combined with secrets.

secrets: a list of NAMES, not values (e.g. ["github_token"]); each is resolved server-side, fed over SSH stdin (never on argv/audit), exported as its uppercased env var ($GITHUB_TOKEN), and redacted to *** in the output. Cannot be combined with use_sudo.

Returns one dict {host, command, exit_code, stdout, stderr, elapsed_s} for a single host + command, else a JSON list (a multi-command host carries {host, results:[…]}).

★ When use_sudo or secrets is used the result is flagged "high_risk": briefly tell the user you ran a privileged / credentialed command with their stored sudo password / secret, or only do so with their explicit prior permission.