Cloud Assistant is a native systems management tool for Elastic Compute Service (ECS). It enables you to execute batch commands (Shell, PowerShell, Bat) on ECS instances without requiring SSH keys, RDP passwords, or bastion hosts. Cloud Assistant allows you to automate O&M tasks, such as running scripts, monitoring processes, installing/uninstalling software, managing services, and applying security patches.
Key features
Batch operations
Execute commands across multiple instances where Cloud Assistant Agent is installed simultaneously. Execution is isolated. Failure on one instance does not affect others.
File upload
Upload local configuration files, scripts, or other assets directly to ECS instances.
Public commands
Access a library of pre-configured scripts and plugins (public commands) for common tasks such as security checks, system patching, and application installation. These vetted templates streamline complex configurations and improve operational efficiency.
Flexible parameterization
Use custom or built-in parameters to create reusable, dynamic commands applicable to multiple scenarios.
Security and control
Cloud Assistant operates on a user-driven model. It does not initiate actions on its own. You retain full control over all operations.
Use cases
Cloud Assistant streamlines deployment and O&M workflows, including but not limited to:
Upload and execute O&M scripts.
Run existing scripts residing on instances.
Manage the software development life cycle.
Deploy code or applications.
Poll process status.
Install patches or security updates.
Fetch updates from Object Storage Service (OSS) or YUM repositories.
Modify hostnames or reset user credentials.
Usage notes
Instances must be Running and have Cloud Assistant Agent installed.
Payload size limits (Base64-encoded):
Create command: Max 18 KB.
Run immediately (Save): Max 18 KB.
Run immediately (No save): Max 24 KB.
Upload file: Max 32 KB.
Parameter limit: Max 20 custom parameters per command.
Cloud Assistant supports the following OS distributions:
Alibaba Cloud Linux
CentOS 6, 7, 8, and later
CoreOS
Debian 8, 9, 10, and later
OpenSUSE
RedHat 5, 6, 7, and later
NoteRedHat requires manual RPM installation. For guidance, see Install Cloud Assistant Agent.
SUSE Linux Enterprise Server 11, 12, 15, and later
Ubuntu 12, 14, 16, 18, and later
FreeBSD 11, 12, 13, 14, and later
Windows Server 2012, 2016, 2019, and later
NoteCloud Assistant Agent is installed by default on ECS instances that are created from public images.
For instances that are created from custom images or Alibaba Cloud Marketplace images, verify OS compatibility and manually install the agent if necessary. For more information, see Install Cloud Assistant Agent.
Feature compatibility matrix
The following table lists supported features and the minimum required Agent version.
Feature | Min version (Linux) | Min version (Windows) |
Agent eartbeat reporting | 1.0.2.458 | 1.0.0.149 |
File distribution | 1.0.2.569 | 1.0.0.149 |
Run as specific user | 2.2.0.106 | 2.1.0.50 |
Run on next boot | 2.2.0.46 | 2.1.0.50 |
Run on every boot | ||
Session Manager support | 2.2.3.196 | 2.1.3.196 |
Scheduled tasks (Rate/At expressions) | 2.2.3.282 | 2.1.3.282 |
Scheduled tasks (Cron with Year/TimeZone) | 2.2.3.282 | 2.1.3.282 |
Built-in environment parameters | 2.2.3.309 | 2.1.3.309 |
Instance names as parameter | 2.2.3.344 | 2.1.3.344 |
Stop or restart via exit code | 2.2.3.317 | 2.1.3.317 |
Container execution (by name) | 2.2.3.344 | 2.1.3.344 |
Container execution (by ID) | 2.2.3.344 | 2.1.3.344 |
Agent architecture and directory structure
Linux
On Linux instances, the Cloud Assistant Agent is installed in /usr/local/share/aliyun-assist/. The file system hierarchy and component descriptions are as follows:
Root directory: /usr/local/share/aliyun-assist/
2.x.x.xxx/: Installation directory for specific versions. For example, 2.2.4.965/
acs-plugin-manager: The plugin management utility.
aliyun_assist_update: The auto-update utility for the Agent.
aliyun_installer: Deprecated. An early component installer, now superseded by
acs-plugin-manager.aliyun-service: The core binary of the Cloud Assistant Agent.
assist_daemon: The daemon process (watchdog) that monitors
aliyun-serviceand ensures stable operation.config/: The directory for configuration files.
GlobalSignRootCA.crt: The root certificate used for secure HTTPS communication with the Cloud Assistant server.
hash_file: Contains cryptographic hashes of program files. Used for integrity checks to detect tampering.
init/: The directory for installation and uninstallation scripts.
clean: Cleanup script to remove configurations and residual files.
install: Installation script.
uninstall: Uninstallation script.
version: A text file recording the current client version.
log/: The directory for log files.
aliyun_assist_main.log: The active log file for the current day..
aliyun_assist_main.log.YYYYMMDD: Archived historical logs (rotated daily).
plugin/: The directory for plugins and related data.
ACS-ECS-SysInfoGatherer: A pre-installed plugin for system information collection.
cache/: The directory for cache files.
state_configs.json: Locally cached configuration for the OOS (Operation Orchestration Service) Inventory collection.
config/: Global configuration directory.
task_sign_certs/: Stores locally cached public keys used to verify the digital signatures of tasks.
hybrid/: The directory for managed instance registration information.
hardwareHash: A hardware fingerprint file generated during registration to uniquely identify the machine.
plugin/: The directory for Cloud Assistant plugins.
installed_plugins.db: A database record of installed plugins.
work/: The directory where execution files are stored.
script/: The staging directory for execution scripts.
Note: Starting from version 2.x.3.704, Cloud Assistant no longer persists execution scripts to disk by default. You must manually enable the script-saving feature to view executed files in this directory.
region-id: A text file containing the Region ID where the instance resides.
Windows
On Windows instances, the Cloud Assistant Agent is typically installed in C:\ProgramData\aliyun\assist\. The directory structure and file descriptions are as follows:
C:\ProgramData\aliyun\assist\
2.x.x.xxx/ (for example, 2.1.4.965) - The installation directory for a specific version of the Agent.
acs-plugin-manager.exe: The plugin management utility.
aliyun_assist_update.exe: The auto-update utility for the Agent.
aliyun_installer.exe: The Cloud Assistant installer program.
aliyun_assist_service.exe: The core binary of the Cloud Assistant service.
install.bat: Batch script for installation operations.
install.exe: Executable installer wrapper.
PatchGo.dll: A runtime patch for Windows Server 2008 environments. It mitigates clock drift issues associated with the Go runtime.
version.ini: Configuration file recording the Agent version.
config/: The directory for configuration files.
GlobalSignRootCA.crt: The root certificate used for secure HTTPS communication with the Cloud Assistant server.
hash_file: Contains cryptographic hashes of program files. Used for file integrity checks to detect tampering.
log/: The directory for log files.
aliyun_assist_main.log: The active log file for the current day.
aliyun_assist_main.log.YYYYMMDD: Archived historical logs (rotated daily).
plugin/: The directory for pre-installed and active plugins.
ACS-ECS-SysInfoGatherer: The system information collection plugin.
SessionManager: The plugin that enables password-free session management (Session Manager).
installed_plugins.db: A database record of installed plugins.
cache/: The directory for cache files.
state_configs.json: Locally cached configuration for the OOS (Operation Orchestration Service) Inventory collection.
config/: The directory for configuration files.
task_sign_certs/: Stores locally cached public keys used by the Agent to verify task signatures.
hybrid/: Directory for Managed Instance (hybrid cloud) registration data.
plugin/: The directory for plugin data.
installed_plugins.db: The data of plugins.
work/: The directory where execution files are stored.
script/: The staging directory for execution scripts.
Note: Starting from version 2.x.3.704, Cloud Assistant no longer persists execution scripts to disk by default. You must manually enable the script-saving feature to view executed files in this directory.
config.ini: Stores global configuration settings, including the current Agent version.
region-id: A text file containing the Region ID where the instance resides.
version: A text file recording the current version of the Cloud Assistant client.
Billing
Cloud Assistant itself is free of charge.
You are only billed for the underlying ECS resources (compute, network, storage) consumed during task execution. See Billing overview.
Resource overhead
The Cloud Assistant Agent is designed to be lightweight.
Resource | Linux | Windows |
CPU | < 1% average utilization | |
Physical memory | About 20 MB | About 30 MB |
Disk I/O | Negligible (peaks only during upgrades or script saving) | |
Network I/O | Minimal (heartbeat traffic) | |
Terms
The following table describes common terms related to Cloud Assistant.
Term | Description |
Cloud Assistant | The service name. Available in all Alibaba Cloud regions. |
Cloud Assistant Agent | The client-side binary running on the instance.
|
AssistDaemon | A watchdog process that monitors and restarts the Agent if it crashes.
Note Linux only. |
Working directory | The path where scripts are temporarily staged (if enabled):
|
Command | The operation payload (Shell, PowerShell, Bat) |
Custom parameter | Variables defined using {{key}} syntax, with values injected at runtime ({{"key":"value"}}). To optimize usage against regional command quotas, we recommend using parameters to create flexible, reusable command templates. You can also utilize built-in environment parameters, which Cloud Assistant automatically populates at runtime without manual input. |
One-time execution | A single execution event on one or more instances. This is also called an invocation ( |
Scheduled execution | A command configured to run periodically (Cron/Rate). |
Command execution status
Instance-level status
The following table describes the instance-level statuses of a command run on an instance. These statuses correspond to the InvocationStatus field under InvokeInstance in DescribeInvocations, or the InvocationStatus field in DescribeInvocationResults.
Status code | Overall status | Aggregation condition |
| Sending | The system is verifying or sending the command. |
| Verification failed | The specified command type or parameter is invalid. |
| Send failed | Failed to send. The instance must be in the |
| Running | The command is being executed. |
| Succeeded |
|
| Execution finished, non-zero exit code |
|
| Execution error | An exception occurred. |
| Execution timed out | Execution exceeded the specified timeout period. |
| Cancelled | Execution was cancelled. |
| Stopping | Execution is being stopped. |
| Stopped | Execution was manually stopped. |
| Terminated | Execution was terminated during runtime. |
| Pending execution | The scheduled command is waiting to be executed. |
Batch/Invocation status
For batch or scheduled executions, Cloud Assistant aggregates the individual statuses of all target instances into a single overall invocation status. This status is returned in the InvocationStatus field of the DescribeInvocations API response.
The following table describes how the instance-level statuses are aggregated to determine the overall status..
Status Code | Description | Aggregation condition |
| The system is verifying or sending the command. | Returns |
| The scheduled command is waiting to be executed. | Returns |
| The command is being executed. | Returns |
| The command is successfully executed | Returns Success when: All instances have finished (Status is
|
| Execution finished with non-zero exit code | Returns
|
| Execution is being stopped. | Returns |
| Execution was manually stopped. | Returns
|
| Mixed results (Some succeeded, some failed). | Returns |
Permissions (RAM)
By default, the Alibaba Cloud account has full access. Do not use it for O&M. Create a Resource Access Management (RAM) user and grant only the necessary permissions. For instructions, see Grant permissions to a RAM user to use Cloud Assistant.
Use Cloud Assistant
You can interact with Cloud Assistant via the Console, API, or SDK.
Scenario | References | Related APIs |
Install agent if necessary. Note:Cloud Assistant Agent is pre-installed by default on ECS instances that are created from public images after December 1, 2017. | ||
Programmatic access via SDK. | Not applicable | |
Create command. | ||
Execute command. | ||
Check status/output. | ||
Modify command. | Not applicable | |
Clones an existing command to create a new one. This allows you to iterate with new versions or modify fundamental properties (like name, type, content, and execution path). | Not applicable | |
Stop execution. | ||
Delete command. |