Elastic Compute Service:Install Workbench CLI and Configure Credentials

Limits

• Operating system of the target instance: Workbench CLI supports connecting only to Linux instances (over the SSH protocol). It does not support connecting to Windows instances.

• Operating system of the local machine: Workbench CLI itself can run on Linux, macOS (amd64 / arm64), and Windows (amd64).

• Network connectivity: The local machine must be able to access *.aliyuncs.com and the Workbench backend WebSocket endpoint.

Step 1: Install Workbench CLI

Choose the installation command based on the operating system of your local machine. The installation script automatically detects the architecture (amd64 / arm64), downloads the binary from the OSS CDN, verifies its SHA256 checksum, and installs it to the system default path.

curl -fsSL https://workbench-cli.oss-cn-hangzhou.aliyuncs.com/install.sh | bash

irm https://workbench-cli.oss-cn-hangzhou.aliyuncs.com/install.ps1 | iex

workbench version

Step 2: Prepare an AccessKey with the Minimum Permissions for Workbench CLI

Workbench CLI calls Alibaba Cloud APIs by using an AccessKey. The goal of this step is to obtain an AccessKey that has only the minimum permissions required by Workbench CLI, so that you can configure it in the local CLI in the next step. The recommended process is: create a RAM user → grant minimum permissions → create an AccessKey for the RAM user.

1. Create a RAM user. Log on to the RAM console, go to the Identities > Users page, and click Create User. On the creation page, enter the Logon Name and Display Name, and then click OK.

   Do not create an AccessKey at this point. The AccessKey is created together after permissions are granted in Step 4.

2. Create a custom permission policy. On the Permissions > Policies page of the RAM console, click Create Policy, switch to the Script mode/JSON mode, paste the following JSON, and then click OK.

     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ecs-workbench:*"
         ],
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": [
           "ecs:DescribeInstances"
   
   
         ],
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "ram:CreateServiceLinkedRole",
         "Resource": "*",
         "Condition": {
           "StringEquals": {
             "ram:ServiceName": "workbench.ecs.aliyuncs.com"
           }
         }
       }
     ]{
   

   The purpose of each Action in the policy is as follows:

   Action	Purpose
   ecs:DescribeInstances	Allows workbench list ecs to query the instance list.
   ecs:DescribeCloudAssistantStatus	Checks the Cloud Assistant agent status of the target instance.
   ecs:StartTerminalSession	Establishes a terminal session with an ECS instance.
   ecs-workbench:LoginECSInstance	Enables password-free logon over the Workbench channel (used by connect, exec, upload, and download).
   ecs-workbench:ChatMessages	The permission required by the in-session AI agent assistant (/agent mode).
   ecs-workbench:EndSessions	Closes Workbench sessions (called by session close and during automatic session cleanup).
   ram:CreateServiceLinkedRole	Creates the Workbench service-linked role on first use. The Condition restricts creation to only the service-linked role for the workbench.ecs.aliyuncs.com service.

   By default, the policy grants access to all instances. To narrow it to specific instances, apply an instance ARN only to the actions that support instance-level authorization (note that the two action groups use different ARN formats). Split them into separate Statement blocks and modify the Resource:

   // ecs-workbench:LoginECSInstance
   "Resource": "acs:ecs:<region>:<account-id>:ecs/<instance-id>"
   
   // ecs:DescribeInstances / DescribeCloudAssistantStatus / StartTerminalSession
   "Resource": "acs:ecs:<region>:<account-id>:instance/<instance-id>"

   Note

   ecs-workbench:ChatMessages and ram:CreateServiceLinkedRole do not support narrowing by instance ARN. Keep "Resource": "*" for them.

3. Grant the policy to the RAM user. Go to the details page of the RAM user created in Step 1, switch to the Permissions tab, click Grant Permission, select the custom policy created in the previous step, and complete the authorization. For more information, see Grant permissions to a RAM user.

4. Create an AccessKey for the RAM user. On the Credentials > AccessKey tab of the RAM user details page, click Create AccessKey. In the dialog that appears, select Use AccessKey in CLI, select I confirm that I must create an AccessKey, and then click Continue to create. For more information, see Create an AccessKey pair.

   Important

   The AccessKey Secret is displayed only once when it is created and cannot be viewed again after the page is closed. Immediately save the AccessKey ID and Secret to a password manager or key vault. If you lose them, you can only create a new AccessKey.

   An AccessKey is a long-term credential. Once leaked, it can be abused over a long period. In production environments, we recommend that you switch to an automatically refreshing credential mode such as RamRoleArn immediately after you complete the configuration in Step 3. For more information, see the More configuration methods section of this document.

Step 3: Configure the AccessKey in the Local CLI

Run the following command, and enter the AccessKey ID and AccessKey Secret obtained in Step 2 as prompted.

workbench config

After the configuration is complete, the credentials are saved in ~/.workbench/config.json, and the file permissions are automatically set to 0600 (readable and writable only by the current user). The following is an example of the file content:

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "LTAI...",
      "access_key_secret": "..."
    }
  }
}

Run the following command to verify whether the connection is established (replace cn-hangzhou with your actual region):

workbench list ecs -r cn-hangzhou

Under normal conditions, the command returns the list of instances in the region. If an error such as InvalidAccessKeyId or NoPermission is returned, see the FAQ section of this document.

(Optional) Set the interface language

Workbench CLI supports Chinese (zh) and English (en) for the interface language. The default is Chinese. Run the following commands to switch:

workbench config set language en   # Switch to English
workbench config set language zh   # Switch back to Chinese

You can also set it during the workbench config interactive flow, or directly edit ~/.workbench/config.json to add the language field to the corresponding profile:

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "language": "en"
    }
  }
}

The change takes effect the next time you connect. You do not need to restart the daemon.

(Optional) Manage Multiple Profiles

If you need to switch between multiple Alibaba Cloud accounts or multiple sets of credentials, you can use the profile feature to avoid repeatedly reconfiguring. All profiles are saved in the same ~/.workbench/config.json file, and the current field marks the active profile.

workbench config --profile prod          # Create or edit the profile named prod
workbench config list                    # List all profiles (* marks the active one)
workbench config get --profile prod      # Show the details of a specific profile
workbench config switch --profile prod   # Switch the active profile
workbench config delete --profile old    # Delete a profile (cannot delete the active one)
workbench exec -i i-xxx -c "hostname" --profile prod   # Use a specific profile for this command only

The following is an example of the multi-profile structure in config.json:

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "LTAI...",
      "access_key_secret": "..."
    },
    "prod": {
      "mode": "RamRoleArn",
      "access_key_id": "LTAI...",
      "access_key_secret": "...",
      "ram_role_arn": "acs:ram::123456:role/prod",
      "role_session_name": "workbench"
    }
  }
}

More Configuration Methods

A long-term AccessKey is a long-term credential. Once leaked, it can be abused over a long period. In production environments or when you have stricter security requirements, we recommend that you switch to one of the following four modes:

workbench config --mode StsToken

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "StsToken",
      "access_key_id": "STS.LTAI...",
      "access_key_secret": "...",
      "sts_token": "..."
    }
  }
}

workbench config --mode RamRoleArn

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "RamRoleArn",
      "access_key_id": "LTAI...",
      "access_key_secret": "...",
      "ram_role_arn": "acs:ram::123456789:role/WorkbenchRole",
      "role_session_name": "workbench-session"
    }
  }
}

workbench config --mode CredentialsCmd

// Long-term AccessKey
{
  "mode": "AK",
  "access_key_id": "<AccessKeyID>",
  "access_key_secret": "<AccessKeySecret>"
}

// STS temporary credentials
{
  "mode": "StsToken",
  "access_key_id": "<AccessKeyID>",
  "access_key_secret": "<AccessKeySecret>",
  "sts_token": "<SecurityToken>"
}

workbench config --mode CredentialsURI

{
  "Code": "Success",
  "AccessKeyId": "<AccessKeyID>",
  "AccessKeySecret": "<AccessKeySecret>",
  "SecurityToken": "<SecurityToken>",
  "Expiration": "2026-01-01T12:00:00Z"
}

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "CredentialsURI",
      "credentials_uri": "http://localhost:8080/credentials"
    }
  }
}

Upgrade Workbench CLI

Workbench CLI supports one-command self-upgrade. Run the following command to upgrade to the latest version:

workbench upgrade

The upgrade automatically downloads and verifies the latest binary and replaces the current version.

Uninstall

Workbench CLI does not register a system service or modify system configurations. To uninstall it, you only need to stop the daemon, delete the binary, and optionally delete the local configuration directory.

workbench daemon stop
sudo rm -f /usr/local/bin/workbench
rm -rf ~/.workbench

workbench daemon stop
Remove-Item "$env:ProgramFiles\workbench" -Recurse -Force

# Remove the shim created during Cloud Assistant-based installation
Remove-Item "$env:SystemRoot\System32\workbench.cmd" -Force -ErrorAction SilentlyContinue

Remove-Item "$env:USERPROFILE\.workbench" -Recurse -Force

# Clean up the workbench path added to the user PATH by the installation script (Remote Desktop scenarios)
$path = [Environment]::GetEnvironmentVariable("Path", "User")
if ($path -match "workbench") {
    $cleaned = ($path -split ";" | Where-Object { $_ -notmatch "workbench" }) -join ";"
    [Environment]::SetEnvironmentVariable("Path", $cleaned, "User")
}

FAQ

chmod 600 ~/.workbench/config.json

References

• Connect to an instance by using Workbench CLI: The parent topic, which covers tool positioning, the capability matrix, and quick start.

• Manage ECS instances by using Workbench CLI: Detailed descriptions of each command and common scenarios.

• Operate ECS instances by using Workbench CLI in AI agents: Integrate Workbench CLI into AI programming tools.

• Grant permissions to a RAM user

• Create an AccessKey pair

• What is STS?

• Install the Cloud Assistant agent