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.
All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.
Summary
| Tool | Description | Access |
|---|---|---|
list_commands | List recent command execution history | Read-only |
execute_command | Run a command on a server and wait for the result | Additive |
execute_command_multi_server | Run the same command on multiple servers | Additive |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | No | Filter results to commands run on this server |
limit | integer | No | Maximum number of results to return (default: 20) |
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 needs sudo and the caller lacks a matching Work Session sudo policy or a required MFA step-up, the tool returns a structured pending-approval result instead of the raw denial—surface this to a human so they can approve it in the Alpacon web console or add the command to the session’s sudo policy, then retry.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Target server ID |
command | string | Yes | Shell command to execute |
shell | string | No | Shell to run the command in (default: system) |
username | string | No | System user to run the command as |
groupname | string | No | System group to run the command as (default: alpacon) |
env | object | No | Environment variables to set for the command |
run_after | array | No | Command IDs this command should run after |
scheduled_at | string | No | Schedule the command for a future time instead of running immediately |
data | string | No | Data to pass to the command’s stdin |
timeout | integer | No | Seconds to wait for completion before timing out (default: 300) |
work_session_id | string | No | Work Session to link this command to, for audit. Falls back to ALPACON_WORK_SESSION if omitted |
Example
“Run
df -hon 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
| Parameter | Type | Required | Description |
|---|---|---|---|
server_ids | array | Yes | Target server IDs |
command | string | Yes | Shell command to execute |
shell | string | No | Shell to run the command in (default: system) |
username | string | No | System user to run the command as |
groupname | string | No | System group to run the command as (default: alpacon) |
env | object | No | Environment variables to set for the command |
parallel | boolean | No | Submit to all servers concurrently (default: true); set false to submit sequentially |
work_session_id | string | No | Work Session to link these commands to, for audit. Falls back to ALPACON_WORK_SESSION if omitted |
Example
“Run
systemctl status nginxon 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