The CloudRay Agent is a lightweight binary that securely connects your Linux machines to the CloudRay platform. It collects system metrics, enables remote task execution, and integrates seamlessly with the CloudRay dashboard — all without needing SSH access.

TIP

You must have a CloudRay account and project set up. You will find the REG_CODE in your project dashboard at app.cloudray.io

Supported Linux Distributions

CloudRay supports the following Linux distributions:

  • Ubuntu 18.04 and newer
  • Debian 10 and newer
  • CentOS 7 and newer
  • RHEL 7 and newer
  • Fedora 32 and newer
  • Amazon Linux 2

For other distributions, the Agent may still work but is not officially supported.

Installation Steps

  1. Open a terminal on your Linux machine and run:
curl -sSfL https://cloudray.io/install.sh | sudo bash
sudo cloudray-agent install-service --reg-code <REG_CODE>

Replace <REG_CODE> with your actual registration code from the CloudRay dashboard.

NOTE

The script is idempotent meaning it’s safe to run multiple times. It will update the Agent if a newer version exists or leave it untouched if already up-to-date.

  1. Check the status of the Agent service:
systemctl status cloudray-agent

You should see the service active and running.

  1. Visit the CloudRay dashboard, navigate to Machines, and confirm your Linux machine appears as connected.

Manual Build from Source

If you’re a developer or contributor, you can build the Agent from source using Rust.

Refer to the main Agent documentation for build instructions.

Troubleshooting

If you encounter errors:

  • Ensure your system has outbound internet access
  • Make sure your shell environment includes Rust tools if building manually
  • Run this if rustc or cargo is not found:
source $HOME/.cargo/env

For more help, visit our GitHub repo or contact support.

Alternative: Connect via SSH

If you are unable to install the Agent on your server, CloudRay also supports management over a secure SSH connection. However, some advanced features may not be available via SSH.

To learn more about managing machines using SSH, see the Managing Server SSH Keys documentation.