Search The Hostwinds Guides Knowledge Base

The Hostwinds Cloud Agent

Share This Article [TheChamp-Sharing]

Included in our VPSes (managed and unmanaged) is the Hostwinds Cloud Agent, a suite of tools that interface the OS inside the VPS to the API for Cloud Control. The Cloud Agent is responsible for setting the IP address, root/Administrator password, hostname, and SSH keys inside the OS of the VPS. It runs automatically during boot to make sure changes within Cloud Control are reflected inside the server. The Cloud Agent is used for setting up Cloud Backups and keeps your OS software up to date.

The Cloud Agent has several routines:

  • boot_service, which ensures the Cloud Agent will run all the enabled routines at boot
  • network, which sets the IP address, default gateway, and DNS servers
  • update, to update the Hostwinds Cloud Agent itself
  • hostname, to set the server hostname (Linux only)
  • password, which syncs the root/Administrator password from Cloud Control
  • ssh_keys, which syncs SSH keys from Cloud Control (Linux only)
  • update_packages, which updates all OS packages (e.g. `yum -y update` or `apt update && apt upgrade`)
  • cleanup, which cleans any leftover files after the above routines are run
  • backups, for installing and managing Cloud Backups
  • package, used by Hostwinds to install specific packages in the VPS creation process

The first 8 routines are enabled by default on a new VPS install, but can be manually modified as below.

Working with the Hostwinds Cloud Agent

The Cloud Agent is a command line tool that can be run from the VNC console, SSH, or inside a cmd or PowerShell window. As shown by the –help option, the normal usage is:

hwagent routine ROUTINE [arguments]

Of note, the run-all argument will only run all the routines already set to run automatically at boot.

To see more information about a specific routine and the arguments available, run

hwagent routine ROUTINE

with no arguments.

Backups routine

To view the status of Cloud Backups on your server:

hwagent routine backups --status

This will show if the backups are enabled/installed, the location, retention period, number of backups available, and the time/date of the most recent backup.

If you’ve purchased the Cloud Backups service, a ticket will be auto generated for our team to run the backups install command and verify its set up and configured. Once this has been done, you will receive an update through our ticketing system that this has been set up and is ready for use during the next scheduled backup within the next 24 hours. You may may also run this set up anytime if you need to re initiate backups for your Cloud VPS server:

hwagent routine backups --install

If you want to manually run a backup without waiting for the next cron to run, simply run

hwagent routine backups --run

This will take a few minutes to complete, depending how much has changed in the server since the last backup.

You can also change the retention period for your Cloud Backups:

hwagent routine backups --retention DAYS

Where DAYS is the number of days worth of restic snapshots to retain. If the number is lower than the current number of restic snapshots, the system will prune older snapshots the next time backups run. You can of course use hwagent routine backups --run to immediately prune them.

If for some reason you want to remove the backup service from the OS, run

hwagent routine backups --uninstall

This will remove restic and the cron job, but it will not cancel the service or any charges. Please make a ticket to the Billing department to cancel the Cloud Backups add-on.

Similarly, if you want to uninstall restic AND remove the storage for Cloud Backups from your Object Storage, run

hwagent routine backups --uninstall --purge

Note: This cannot be run after –uninstall, and will not completely remove the Object Storage container, just delete the contents of it. If you want to stop being billed for Object Storage, you will have to delete the container manually.

After either variant of –uninstall has been run, you can run hwagent routine backups --install to reinstall restic and add the backup cron job to the OS again.

Other Routines

The other routines include several simpler tools that can be disabled, enabled, or run manually:

  • hostname – update the server hostname
  • network – update static IP configuration
  • password – update root password to the one specified in the cloud
  • ssh_keys – add ssh keys from the cloud to the root user’s authorized keys
  • update – update the Hostwinds Cloud Agent and re-run
  • update_packages – update system software packages

Note that these all require root/Administrator permissions as they modify system files/properties. The command structure is:

hwagent routine ROUTINE --[enable|disable|run]

For example, if you have a custom hostname setup in your server and don’t want it to be reset to hwsrv-XXXX on reboot, run

hwagent routine hostname --disable

Or if you’ve changed the password or SSH keys in Cloud Control and don’t want to reboot the server to set them, use

hwagent routine password --run


hwagent routine ssh_keys --run


It is not recommended to disable the network routine, but if you do and lose connection to the server, you can log in through Actions -> Get VNC in the Cloud Portal and re-enable it with

hwagent routine network --enable
hwagent routine network --run

By default, all of the routines are enabled and run each bootup in the order listed above, with hostname, ssh-keys, and password run in parallel.

We hope you enjoy this glimpse into the automation running behind the scenes to make your VPS run smoothly, and have found the tools provided to be useful. If you have any questions, or need any assistance, feel free to reach out to our Support Team 24/7/365 by opening a Support Ticket.