local_exec
Execute commands directly on the MCP server machine, with optional sudo and credential injection via named secrets. Requires explicit enablement and a timeout.
Instructions
Run a command on the MCP SERVER's OWN machine (local), NOT over SSH — for anything on a remote host use remote_exec instead. This departs from the project's core goal (driving remote hosts as if local); it's a useful but off-target derivative, so it is OFF by default: the operator must explicitly set PORTAL_ALLOW_LOCAL_EXEC=1 in the server process's env to enable it.
★ credentials: if the command needs a secret, don't 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), injected into the local child's env and redacted from output. This
lets a local script use an API token without the value ever entering this
conversation.
★ use_sudo: run the command under sudo on THIS machine (local_exec). The
sudo password is resolved out-of-band (NEVER an argument): the per-user
credential agent populated by portal sudo set-local, or a top-level
<local>: section's sudo_password_command in hosts.yaml. Fed to sudo -S -k
on stdin (never on argv/audit). May be combined with secrets (their values
ride the same stdin channel, read+exported inside the sudo'd shell). This is
the LOCAL counterpart of remote_exec(use_sudo=True); the reserved identity
<local> is distinct from any SSH host named local / localhost.
timeout (seconds, REQUIRED — no default): held open until the command exits or timeout elapses. Keepalive pings stop the client aborting a hung call, so pass a SMALL one for an exploratory / re-runnable command (e.g. 10–30) to fail fast, raising it only for a genuinely slow but bounded command. Hard ceiling (PORTAL_MAX_TIMEOUT, default 300s): a request above it is refused — local_exec has no background runner, so split the work into shorter steps.
★ secrets flags the result "high_risk": briefly tell the user you ran a local command with their stored credential, or only do so with prior permission.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| secrets | No | ||
| timeout | Yes | ||
| use_sudo | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |