canonical: https://jentic.com/apis/azure.com/runcommandsclient

# Microsoft Azure RunCommandsClient

Jentic publishes the only available OpenAPI specification for RunCommandsClient, keeping it validated and agent-ready. The Azure Compute Run Commands API lets agents execute scripts on Azure virtual machines and Virtual Machine Scale Set instances without opening RDP, SSH, or installing additional agents. It exposes the catalogue of supported commands per region and triggers script execution against a specific VM or VMSS instance, returning a long-running operation handle for polling. This is the standard mechanism for ad-hoc remote execution on Azure VMs.

## For AI agents

Run scripts on Azure virtual machines and Virtual Machine Scale Set instances and list the catalogue of available run commands per region.

## Scope

Does not provision VMs, manage networking, or schedule recurring jobs - use for executing ad-hoc scripts on existing Azure VMs and VMSS instances only.

## Capabilities

- Execute a run command on a single virtual machine in a resource group
- Execute a run command on a specific Virtual Machine Scale Set instance
- List the catalogue of run commands available in a given Azure region
- Retrieve the schema and input parameters for a specific run command id
- Capture stdout and stderr output from a remote script execution
- Drive in-VM remediation without opening SSH or RDP ports

## Use cases

### Emergency Remote Execution Without SSH

When a VM has lost network connectivity or its SSH service has stopped, operators still need to run diagnostic or recovery scripts. The Run Commands API executes scripts via the Azure platform agent rather than the network, so it works even when inbound SSH or RDP is blocked. The POST endpoint accepts a command id and parameters and returns a long-running operation that streams stdout and stderr back through Azure Resource Manager.

Example prompt: POST /subscriptions/{subscriptionId}/resourceGroups/{rg}/providers/Microsoft.Compute/virtualMachines/{vmName}/runCommand with commandId RunShellScript and a script body, then poll the long-running operation until it completes

### Bulk Configuration Across a Scale Set Instance

When a single instance of a Virtual Machine Scale Set drifts out of compliance, operators can target that one instance with a run command rather than redeploying the whole scale set. The instance-scoped endpoint accepts the same command catalogue as standalone VMs and returns the same long-running operation contract. Output is captured per call so subsequent automation can decide whether to scale the instance out.

Example prompt: POST runCommand on virtualMachineScaleSets/{vmssName}/virtualmachines/{instanceId} with commandId RunShellScript and parameters that restart the failing service

### Run Command Catalogue Discovery

Before executing a remote script, agents need to confirm the target region supports the desired command id and understand what parameters it accepts. The list endpoint returns every command id available in a region with its description, and the GET-by-id endpoint returns the full input schema. Pairing these two calls lets an agent build a parameterised script invocation without consulting external documentation.

Example prompt: GET runCommands for location westus2, find the command with id RunPowerShellScript, then GET runCommands/RunPowerShellScript to fetch its input schema

### Agent-Driven VM Remediation via Jentic

Through Jentic, an SRE agent can search for run script on azure vm, load the input schema for the runCommand POST, populate it with the target script, and execute the call with a managed Azure OAuth token. The same flow handles VMSS instances by selecting the matching operation. The agent never holds a service principal secret directly.

Example prompt: Search Jentic for run script on azure vm, load the runCommand POST schema, execute it for vm web-01 with a shell script that flushes the local cache, and return the captured stdout

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.Compute/locations/{location}/runCommands | List run commands in a region |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.Compute/locations/{location}/runCommands/{commandId} | Get input schema for a command |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/runCommand | Run a command on a VM |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmScaleSetName}/virtualmachines/{instanceId}/runCommand | Run a command on a VMSS instance |

## Key resources

- **RunCommands** — List the catalogue of run commands available per region and fetch input schemas
- **VirtualMachines** — Execute a run command against a single VM in a resource group
- **VirtualMachineScaleSetVMs** — Execute a run command against a specific instance of a Virtual Machine Scale Set

## Why Jentic

- **Setup:** Wiring RunCommandsClient by hand means registering an Azure AD app, running the OAuth2 azure_auth token exchange for the management.azure.com audience, and branching your path plus polling logic between standalone VM and scale-set-instance targets. Through Jentic you install once, import RunCommandsClient from the API Directory, store the Azure service principal credential once, and your agent calls it.
- **Permission scoping:** RunCommandsClient puts the subscription, resource group, and virtual machine name in the URL path (.../virtualMachines/{vmName}/runCommand), so a rule can pin your agent to one VM or scale set. You choose the operations it may call, so you can allow listing the command catalogue while withholding the runCommand execution itself unless you add it.
- **Credential handling:** Your Azure service principal credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a script on an Azure VM' or 'execute PowerShell on a scale set instance', and Jentic returns the matching RunCommandsClient operation with its input schema for either standalone VM or VMSS instance scope.

## Related APIs

- **Azure ComputeManagementClient** — Manages the lifecycle of the VMs and scale sets you run commands on
- **Azure RemediationsClient** — Policy-driven ARM remediation rather than imperative VM scripts
- **Azure AutomationManagementClient** — Scheduled and orchestrated runbooks for repeatable VM operations

## FAQ

### Why is there no official OpenAPI spec for RunCommandsClient?

Microsoft Azure does not publish a unified OpenAPI specification covering the Compute Run Commands API. Jentic generates and maintains this spec so that AI agents and developers can call RunCommands via structured tooling. It is validated against the live Azure Resource Manager API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the RunCommandsClient API use?

It uses Azure Active Directory OAuth 2.0 via the azure_auth flow defined in the spec. Acquire a bearer token for https://management.azure.com/.default and pass it as Authorization: Bearer. Through Jentic, the underlying service principal lives in the vault and the agent only sees a scoped token.

### Can I run a PowerShell script on an Azure VM through this API?

Yes. POST to .../virtualMachines/{vmName}/runCommand with commandId RunPowerShellScript and a script body in the parameters. The same pattern works for shell scripts via RunShellScript. The available command ids in a region come from the list endpoint.

### Does RunCommandsClient work on VM Scale Set instances?

Yes. POST to .../virtualMachineScaleSets/{vmScaleSetName}/virtualmachines/{instanceId}/runCommand with the same body shape as a standalone VM. This lets you target one drifted instance instead of redeploying the entire scale set.

### What are the rate limits for the RunCommandsClient API?

Calls count against Azure Resource Manager subscription throttling, roughly 1,200 writes per hour per subscription. Each run command is a long-running async operation, so completion time depends on script duration rather than API throughput. Throttled requests return HTTP 429 with a Retry-After header.

### How do I trigger a remote script through Jentic?

Search Jentic for run script on azure vm, call client.load on the runCommand POST operation to receive its input schema, then call client.execute with subscriptionId, resourceGroupName, vmName, commandId, and parameters. Jentic injects the OAuth token and returns the long-running operation handle.

### Can I limit what my agent is allowed to do with the RunCommandsClient API?

Yes. Because you run Jentic One yourself, your own rules decide which RunCommandsClient operations and which Azure credential the agent may use. Since the subscription, resource group, and virtual machine name sit in the URL path, you can pin the agent to a single VM or scale-set instance, and you can allow it to list the run command catalogue and fetch input schemas while withholding the runCommand execution operations unless you explicitly add them. The Azure service principal is held by your instance and injected at call time, so the agent only ever acts within the scope you grant.