Run Shell or PowerShell scripts on multiple ECS instances without logging in.
Commands run with the specified username's permissions. Use a non-root user following the principle of least privilege to minimize security risk.
Prerequisites
Ensure the following:
-
Cloud Assistant Agent is installed on your target instances.
-
Target instances are in the Running state with network connectivity.
-
The executing user has read, write, and execute permissions on the relevant files and directories.
Procedure
Console
-
In the top navigation bar, select the region and resource group.

-
In the upper-right corner of the ECS Cloud Assistant page, click Create/Run Command.
-
In the Command Information section, configure the following:
-
Command content: Paste or type your script.
To use dynamic values, enable Use Parameters and add parameters in
{{parameter}}format:-
Custom Parameters: Defined in
{{parameter}}format. Assign values manually when running the command. -
Built-in parameters: Provided by Cloud Assistant and replaced at runtime — for example,
{{ACS::RegionId}}(region ID) and{{ACS::InstanceId}}(instance ID).
#!/bin/bash # {{name}} is a custom parameter — assign a value when running. echo {{name}} # {{ACS::RegionId}} is a built-in parameter — no value needed. echo {{ACS::RegionId}}Note: Base64-encoded command payload limit: 18 KB for Run And Save, 24 KB for Run.
-
-
Execution Plan: Choose when to run the command.
-
*(Default)* Immediately.
-
Perform Only Dry Run: Validates request parameters, instance environment, and Cloud Assistant Agent status without running the command.
-
Run on Schedule:
-
Run at Fixed Interval: Runs at a fixed interval defined by a rate expression. Must be between 60 seconds and 7 days, and longer than the command timeout.
-
Run on Clock-based Schedule: Uses a cron expression for flexible scheduling.
-
-
-
Username: Defaults to
root(Linux) orSystem(Windows). -
Execution Path: The script's working directory. Defaults to
/root(Linux) orC:\Windows\system32(Windows). To change directory, add acdcommand at the start of the script. -
Timeout: Defaults to 60 seconds. Valid range: 10–86,400 seconds (24 hours).
-
Task Stop Scope: What stops when a task is terminated.
-
Command Process: Stops the script process only.
-
Command Process Tree: Stops the script process and all its child processes.
-
-
-
In the Select Instance or Select Managed Instances section, select the target instances.
Select up to 100 instances per execution. If an expected instance is missing, verify that Cloud Assistant Agent is installed and the instance is in the Running state.
-
Click Run and Save or Run to start.
CLI
All examples use aliyun ecs RunCommand. For the full parameter reference, see RunCommand.
-
Step 1: Encode your script
RunCommandacceptsCommandContentas plaintext or Base64-encoded content. To use Base64 encoding, setContentEncodingtoBase64and encode your script first:Linux / macOS
# Use -n to avoid encoding the trailing newline echo -n "hello world" | base64 # Output: aGVsbG8gd29ybGQ=Windows (PowerShell)
[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("hello world")) # Output: aGVsbG8gd29ybGQ= -
Step 2: Run the command
Run on a single instance
# The Base64-encoded value of "yum -y update" is "eXVtIC15IHVwZGF0ZQ==" aliyun ecs RunCommand --RegionId 'cn-hangzhou' \ --Type 'RunShellScript' \ --ContentEncoding 'Base64' \ --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \ --InstanceId.1 'i-bp1************de01'Run on multiple instances
Specify multiple instances with
--InstanceId.N:aliyun ecs RunCommand --RegionId 'cn-hangzhou' \ --Type 'RunShellScript' \ --ContentEncoding 'Base64' \ --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \ --InstanceId.1 'i-bp1************de01' \ --InstanceId.2 'i-bp1************de02' \ --InstanceId.3 'i-bp1************de03'Run on a schedule (cron)
# Run at 12:00 PM every day in 2024, Asia/Shanghai time zone aliyun ecs RunCommand --RegionId 'cn-hangzhou' \ --Type 'RunShellScript' \ --ContentEncoding 'Base64' \ --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \ --RepeatMode 'Period' \ --Frequency '0 0 12 * * ? 2024 Asia/Shanghai' \ --InstanceId.1 'i-bp1************de01' -
Step 3: Check the results
RunCommandreturns anInvokeId. Query execution results with:# Replace <invoke_id> with your InvokeId aliyun ecs DescribeInvocationResults --RegionId 'cn-hangzhou' --InvokeId '<invoke_id>'See DescribeInvocationResults for parameter details.
In the response, check:
-
Output: the script's standard output (STDOUT) -
ErrorInfoandErrorMsg: error details
-
Limitations
-
Maximum instances per execution: 100. To raise this limit, see Manage quotas.
-
Maximum saved commands per region: 500 by default. Commands run without saving do not count against this quota. To raise this limit, see Manage quotas.
-
Some advanced features require specific Cloud Assistant Agent versions. See Features and versions.
-
Base64-encoded command payload: max 18 KB (Run And Save) or 24 KB (Run).
-
Timeout range: 10–86,400 seconds. Fixed-interval schedules must be at least 60 seconds and exceed the command timeout.
Apply in production
Use idempotence for CLI/SDK calls
Set ClientToken to ensure idempotence when calling RunCommand via CLI or SDK. This prevents duplicate executions from network retries.
Set up monitoring and alerts
Subscribe to Cloud Assistant events through EventBridge or CloudMonitor to get notified on command failures. Early detection reduces time to resolution.
FAQ
How do I check the Cloud Assistant Agent version on an instance?
Check from the console or by logging in to the instance. See Install Cloud Assistant Agent.
For a fixed-interval scheduled task, does it run immediately after creation?
No. The first run occurs after the first interval elapses. For example, a task created at 10:00 with a 10-minute interval first runs at 10:10.
My command failed. How do I troubleshoot it?
Check the Output log on the execution results page — error messages are usually there. Then:
-
Verify the executing user has read, write, and execute permissions on the relevant files and directories.
-
Test the script by running it manually on the instance.
-
Confirm the instance is in the Running state with network connectivity.
-
If the error is
ClientNeedUpgrade, upgrade the Cloud Assistant Agent.
See Check execution results and troubleshoot common issues for a full troubleshooting reference.
Next steps
-
Features and versions — check which features require a specific agent version
-
Manage quotas — raise the instance or saved-command quota
-
Subscribe to Cloud Assistant events — set up failure alerts via EventBridge or CloudMonitor