1. Requirements
| Item | Needed |
|---|---|
| WHMCS | 8.x or later |
| PHP | 8.2 or later with the cURL extension (outbound HTTPS to api.vultr.com and my.whmcsmodule.net) |
| Vultr | An account with Bare Metal enabled and an API key |
| License | A license key in the format VultrBareMetal-Yearly-xxxxxxx |
The Vultr API key has an access control list. Add the public IP address of your WHMCS server to it in the Vultr portal (Account, API), otherwise every call is rejected.
2. Upload the files
Upload the modules folder from the package into the WHMCS root so you end up with:
<whmcs root>/modules/servers/vultr_baremetal/
<whmcs root>/modules/addons/vultr_baremetal/
Both folders are needed: the server module provisions and manages servers, and the addon provides the admin pages. Upload the server module first. Activation refuses to continue without it.
3. Activate the addon and grant access
- Go to Configuration, System Settings, Addon Modules.
- Find Vultr Bare Metal Manager and press Activate.
- Press Configure, tick the admin role groups that may use the addon (for example Full Administrator) and press Save Changes.
Activating the addon also registers the module's hooks with WHMCS (product save, order form styling, settings page layout and the cron sync). Always upload both folders before activating. If you activate first and upload later, press Configure, Save Changes once more so WHMCS rebuilds its hook list.
4. Enter your license
Open Addons, Vultr Bare Metal Manager. Until a valid license is active the addon shows only the License page. Enter your key and press Activate. The key is checked against the license server, then cached for 7 days and re-verified automatically.
The page shows the status, the masked key, the registered name, domain, IP and installation path the license is bound to, and when it was last verified. Recheck License forces a new verification. The key field is always empty; it is never pre-filled.
Without an active license the addon pages, the server dashboard and Create are blocked. Suspend, unsuspend and terminate stay available so services can still be wound down.
5. Connect your Vultr account
- Open API Accounts.
- Enter a name and the Vultr API key and press Add Account. The key is stored encrypted with WHMCS's own encryption and shown only masked.
- Press Test. A green message confirms WHMCS can reach Vultr.
You can disable an account with the toggle, or delete it once no product uses it. Several accounts can exist; each product chooses one.
6. Import a plan as a product
- Open Plans. The list is loaded live from your Vultr account: CPU, RAM, disks, bandwidth, monthly price and the regions where the plan exists.
- Press Import on a plan. In the dialog choose the product name, the product group, the region, the default operating system and an optional price markup in percent, then press Create Product.
The importer creates a WHMCS product that uses this module, adds the Server ID custom field (admin only) and writes the price for every billing cycle (monthly to triennially) in every WHMCS currency, converted with WHMCS's own exchange rates.
7. Review the product settings
Open the product in Configuration, Products/Services, then the Module Settings tab. The settings are grouped into sections and the drop-downs are loaded live from Vultr.

| Section | Setting | Meaning |
|---|---|---|
| Deployment | Account | The Vultr API account used by this product |
| Deployment | Region | Where the server is deployed |
| Deployment | Plan | The bare metal plan (shown with its available regions) |
| Deployment | Operating System | Default OS. A configurable option named OS can override it |
| Deployment | Hostname Prefix | Used when the service has no valid domain |
| Deployment | Enable IPv6 | Ask Vultr for an IPv6 network at deploy time |
| Pricing | Price Markup (%) | Applied when importing prices |
| Client Area Features | Client Reinstall, Console, Network Tab, Traffic Tab, User Data | Show or hide each tab for customers. Admins always see every tab |
| Order Form | Order Form Styling | Restyle the configurable options step of the cart to match the dashboard |
Set Auto Setup to Do not automatically setup while testing, so orders stay pending until you provision them yourself. Choose Automatically setup as soon as the first payment is received for production.
Vultr only offers a plan in regions where it is in stock. If the chosen region is out of stock, Create fails with a clear message that lists the regions that do have the plan.
8. A customer orders a server
The customer picks the product in the store and fills in the order form.
At checkout they log in or register and complete the order.
9. Provision the server
Open the new service from Orders or Clients, Products/Services. It is Pending and the Server ID field is empty. The Module Commands row offers Create, Suspend, Unsuspend and Terminate.
Press Create and confirm. The module checks stock, places the order at Vultr, stores the returned Server ID, the IP address and the generated root password on the service.
Vultr then builds the server, which takes a few minutes. The dashboard shows a Deploying badge and hides the power buttons until Vultr reports the server active.
10. The server dashboard
The same dashboard appears on the admin service page and in the customer's client area. It refreshes the status every 25 seconds and after every action. Every action asks for confirmation first, and results appear as toasts at the top right.
Overview, power and details
The hero card shows the operating system logo, the server name, the state, the main IP, the region (as a readable location such as Amsterdam, NL) and, for admins only, the Vultr server ID. The buttons offered depend on the state: a running server shows Stop and Reboot, a stopped one shows Start. Four tiles show CPU cores, memory, storage and power; they have large coloured icons and animate when you hover over them.
Login details
Show asks for confirmation, then reveals the username (root, or Administrator for Windows) and the password, with a Copy button. Vultr returns the password only when the server is created or reinstalled, so the module stores it (encrypted, in the WHMCS service password) and shows that copy.
Rename
The pencil button next to the name opens an inline editor. Saving changes the server label at Vultr.
Action Protection
A module-level lock. While it is on, Reinstall is blocked on the server side, whatever the browser sends. Use it to protect production servers from an accidental wipe.
Network tab
Lists the IPv4 addresses (netmask, gateway, type, reverse DNS), the IPv6 addresses and the private networks (VPCs) in your Vultr account with Attach and Detach buttons. When IPv6 is not enabled, an Enable IPv6 button asks Vultr for an IPv6 network.
Traffic tab
Choose Today, Yesterday, Last 7 Days, Current Month, Last Month or a Custom date range (validated: valid dates, from before to, at most 92 days). Tiles show incoming, outgoing and total traffic and a bar chart shows each day. Vultr keeps roughly the last 30 days.
Console tab
The tab explains what the remote console is for. Open console asks for confirmation and then opens Vultr's secure console for this server in its own browser window. Allow pop-ups for your site if your browser blocks the window; a banner with a direct link appears if it does.
Vultr's console cannot be shown inside another website. Vultr sends the header
X-Frame-Options: SAMEORIGINwith it, which makes browsers refuse to display it in an iframe on any other domain. That is why the console opens in its own window.
Reinstall tab
Operating systems are grouped by family. Each family is one card with its logo and a drop-down of its versions; the card of the family you picked is highlighted and the current system is marked. Tick the acknowledgement and press Reinstall Server, then confirm. A different OS is installed through Vultr's update call and the same OS through the reinstall call. A reinstall erases all data on the server.
User Data tab
A startup script or cloud-init document (up to 16 KB). It is sent to Vultr base64-encoded and applied at the next reinstall.
Activity tab
Every action taken from the dashboard, who did it (client or admin), when and from which IP address, with a pager.
11. The customer view
Customers see the same dashboard under Services, My Services, Manage, plus a Billing Information card (billing cycle, registration date, first payment, recurring amount, next due date and payment method, in their own currency). The Vultr server ID is never sent to customers. The billing card stays visible after suspension or termination.
12. Admin addon pages
Dashboard: account and service counts and the most recent Vultr API calls.
Servers: every server in a Vultr account, 10 at a time, with the WHMCS service it is linked to. A server that exists at Vultr but has no service can be assigned to a service by entering the service ID, which links it without creating anything new.
Logs: every call WHMCS makes to the Vultr API, with method, endpoint, HTTP status, time and the response. Server passwords and your API key are masked before anything is stored. Entries older than 30 days are removed automatically.
13. Suspend, unsuspend and terminate
These are the standard WHMCS service commands and they act on the real Vultr server.
| Command | What it does at Vultr |
|---|---|
| Suspend | Stops the server (power off) |
| Unsuspend | Starts the server |
| Terminate | Deletes the server permanently and clears the Server ID field |
Billing stops at Vultr when the server is deleted.
14. Automatic background sync
On every WHMCS cron run the module checks up to 25 active services, oldest first. It mirrors the main IP address, server ID and password onto the service and records the month-to-date traffic as the service's bandwidth usage. Make sure the standard WHMCS cron job is configured.
15. Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Test shows a 401 or 403 error | The key is wrong or the WHMCS server IP is not in the key's access control list in the Vultr portal |
| "This plan is currently unavailable in this region" | The plan is out of stock there. Choose a region the message lists, or another plan |
| Settings page is not grouped, order styling or cron sync does nothing | WHMCS has not loaded the module's hooks. Press Configure, Save Changes on the addon in Addon Modules |
| Power buttons are missing and the badge says Deploying | Vultr is still building the server. They appear once it is active |
| "Cannot restart server" | Vultr refuses power actions while a server is building. Wait for it to become active |
| Password is empty | Vultr returns it only at create and reinstall. The module shows the stored copy; reinstall to generate a new one |
| An unlicensed notice appears | The license is missing, invalid or expired. Open the License page and recheck |
| The console window shows "Server disconnected" | The console session expired or the server is rebooting. Close the window and press Open console again |
| The cart empties after login | The product has no price in the customer's currency. Re-import the plan, which prices every currency |
| An error mentions rate limiting | Vultr throttles each API key. The module retries automatically; wait a moment and try again |
16. Security notes
- Every action that changes something is POST-only, protected against cross-site request forgery with two tokens, validated on the server and confirmed by the user.
- The Vultr API key is stored encrypted with WHMCS's encryption and never shown in full or written to logs.
- Server passwords are masked in the API log and shown only after an explicit confirmation.
- Customers can only act on their own service; the Vultr server ID is never sent to them.
- The license secret inside the module is readable by anyone who can read the module files. That is how the licensing server's design works, so protect the server's file permissions accordingly.