Command execution tools

These tools let an AI agent run shell commands on one or more servers and review what has already run. They back requests like “run df -h on web-01 and tell me the result” or “deploy this config to every server in the staging fleet.”

Command execution always requires ACL permission on the caller—see Command ACLs for how those rules are managed. When the caller authenticates through MCP OAuth or a browser session, the server also requires an active Work Session that includes the command scope; static API tokens and service tokens bypass this requirement. Pass work_session_id to link a command to a specific session, or set the ALPACON_WORK_SESSION environment variable to supply a default when the argument is omitted.

Summary

Command history

list_commands

Lists recent commands executed on servers, including status, output, and timestamps. Filter by server_id to scope the history to a single server. Use this to review what has already run before executing something new, or to check the outcome of a command submitted earlier.

Access: Read-only

Parameters

Example

“Show me the last 10 commands run on the db-01 server”

The agent calls list_commands with server_id set to db-01’s UUID and limit=10, returning each command’s status, output, and timestamp.

Running commands

execute_command

Runs a shell command on a server and waits for the result, returning stdout, stderr, and exit code in a single call. This is the recommended way to run a command—list_commands only reviews history, it does not execute anything. The tool polls for completion up to timeout seconds (default 300, i.e. 5 minutes), resetting the deadline while the command is actively running, with a hard cap at three times the timeout to prevent indefinite waiting.

Supports dependency chains (run_after), scheduled execution (scheduled_at), and stdin input (data). If the command reaches a terminal non-result state—denied, rejected, or stuck—the tool stops polling and returns an error immediately instead of waiting out the timeout.

If the command itself needs human approval before it can run at all (a Work Session gate, separate from the sudo handling below), the tool returns a structured pending-approval result with status awaiting_approval. Do not re-run the command while it is pending: resubmitting requires its own separate approval and risks double-executing the command once the original request is approved. Wait for the approval, then check the outcome with list_commands.

If the command needs sudo and hits a non-interactive denial, the tool always attaches a free-text hint describing the denial category. For the three categories a human can resolve out-of-band—a missing Work Session sudo policy, a required MFA step-up, or a pending sudo approval—it additionally attaches a structured pending-approval block alongside that hint, so an agent can branch on a stable category instead of parsing prose. A human can add the command to the session’s sudo policy via the Alpacon web console or the CLI’s work-session update --sudo, complete the step-up, or approve the request, then retry. SUDO_RISK_DENIED is excluded from this—it is a hard denial from runtime risk assessment, not retryable or approvable, and only the free-text hint is returned for it.

Access: Additive

Parameters

If command contains an inline credential—a secret-like KEY=VALUE pair, a password flag, or a connection string with an embedded password—the server rejects the call with command_inline_credential before the command is stored. Pass secrets through env instead; it’s write-only and never appears in command history or audit logs.

Example

“Run df -h on web-01 and show me the disk usage”

The agent calls execute_command with server_id set to web-01’s UUID and command="df -h", waits for the result, and reports stdout back to the user.

“Restart nginx on api-02 inside my current work session”

The agent passes work_session_id (or relies on ALPACON_WORK_SESSION) so the restart is recorded against that session for audit.

execute_command_multi_server

Runs the same shell command on multiple servers, either in parallel (default) or sequentially with parallel=false. Returns per-server success/failure status. This tool only submits the commands—it does not wait for results; use list_commands to check on each one afterward.

Use this for fleet-wide operations: deploying a config change, checking a version, or running the same diagnostic across many servers in one call instead of repeated execute_command calls.

Access: Additive

Parameters

Example

“Run systemctl status nginx on all three web servers”

The agent calls execute_command_multi_server with server_ids set to the three UUIDs and command="systemctl status nginx", then reports which servers succeeded and which failed.

Related

• Work Sessions: create and manage the Work Session required for OAuth and browser-based command execution
• Access control & approvals: manage the command ACL rules that gate execute_command
• File transfer tools: upload and download files to the same servers