Connect a cPanel or DirectAdmin server

Connect your first server

A server, in Panelbot, is a machine where your customers’ hosting accounts live. Panelbot supports cPanel/WHM and DirectAdmin. Connecting one tells Panelbot which machine to work with when a customer needs help.

Panelbot connects over the panel API, the same way your WHMCS or Blesta portal already talks to the server. You grant a scoped credential, Panelbot uses it, and you can revoke it at any time. Nothing is installed on the server, no inbound port is opened, and you do not need root. A reseller credential is enough to start.

There is an optional server agent for the narrow set of jobs a panel credential cannot reach on your setup. Most hosts never need it, and nothing on this page depends on it.

Before you start

Connect from your billing portal (the usual path)

The quickest way to connect is to let your billing portal do it. Open the connect page (Servers, then Connect server). The top line shows your billing connection, for example Billing connected: WHMCS. Tick I understand what this file does with the server credential my billing system stores., then choose Download the billing file for WHMCS (or for Blesta, to match your portal). Panelbot builds the file at download time with your account’s details already inside it, so there is nothing to copy or paste. What this file does, just below the download, lists in plain words what the file does with that credential.

The connector and the chat widget are one install: one file for WHMCS, one plugin for Blesta. It is the same file you get from Widget > Install, so if you download it from either page, that one file puts the chat in your client area and connects your servers.

Install it (the same steps are under More options on the connect page):

• WHMCS. Upload panelbot_hook.php into includes/hooks/ in your WHMCS installation. It replaces a widget-only panelbot_hook.php of the same name. If you installed the older separate connector, also delete includes/hooks/panelbot_connect_hook.php and the includes/hooks/panelbot_connect/ folder.
• Blesta. Extract the download and upload the panelbot directory into plugins/, then install PanelBot Chat Widget under Settings, Company, Plugins, or choose Upgrade if it is already installed (see Embed the widget on your portal). If you installed the older separate PanelBot Connect plugin, uninstall it and delete plugins/panelbot_connect/.

What the connector needs from your portal:

• A working cron. The WHMCS hook sends a server when you add or save it in WHMCS, and after every WHMCS cron run it re-checks your servers for changes and delivers any approved agent installs. Servers that were already in WHMCS before you installed the hook arrive on that cron run, so the WHMCS system cron has to be running. The Blesta plugin adds its own cron task, PanelBot Connect server sync, that runs every 5 minutes on Blesta’s cron.
• A trusted panel certificate, or a CA bundle. The connector always verifies the panel’s TLS certificate, and a brand-new cPanel or DirectAdmin server often serves a self-signed one, which shows up as an “SSL certificate problem” line in the log. Install a trusted certificate on the panel, or point the connector at a CA bundle file holding your system CA bundle plus that panel certificate: PANELBOT_CA_BUNDLE in the server connector section of panelbot_hook.php on WHMCS, or CA bundle path (optional) on the plugin’s manage page in Blesta. Verification is never turned off.
• The newest download, once uploaded. Each download, from the connect page or the Widget page, makes a new connect key. The file you already installed keeps working until you upload the new one. The first time the new file connects, the key inside the older file stops working, so exactly one file per portal stays live. If you download again, replace the old copy with the new one.

From there it runs itself. The connector reads the panel credential your billing system already stores for that server, mints a restricted token named panelbot directly on your server, and sends Panelbot only that token, never the credential your billing system holds. The single exception is the one-time root credential handed over when you approve an agent install; on servers stored with a password, a temporary full-access token is created for that install and revoked immediately after. Nothing is installed on the server itself, and no root access is used to do it.

The file sends Panelbot every cPanel and DirectAdmin server entry in your billing system, including the ones it could not connect and the reason why. The servers then appear under Your servers on the connect page, and on your Servers page, with their capabilities already checked. A short guided walkthrough points out what just happened and what to look at first. There is no multi-step server form to fill in.

Each server on the connect page is one row with its hostname, a plain label, and a status:

• Server (full access), Reseller server (limited access), or VPS or dedicated server tells you what kind of server it is. Server types explained covers each one.
• Connected, Waiting, Could not connect, or Disconnected tells you where it stands. Waiting means Panelbot is still checking what the credential can do.
• Show details opens the server: the credential Panelbot holds, what it can do now, what needs full access, and the Disconnect button.
• Full access: recommended shows on a server connected with a root login (or a DirectAdmin admin login) that has no agent approved yet. It opens that server’s details, where you can approve the server agent.

Your billing portal does not know whether a server is shared hosting or a VPS, so every server the connector delivers for the first time arrives as a shared hosting or reseller server. If it is a VPS or dedicated server, open it on the Servers page, choose Edit server, and set Server role to VPS or dedicated server, with its billing service ID so chats route to it. You only do this once: when the connector sends the same server again, the role you chose is kept. A VPS or dedicated server needs a root login (a DirectAdmin admin login key on DirectAdmin). If the server is connected with a reseller login, Panelbot refuses the change and says: “A reseller login has no root access, so this server cannot be added as a VPS or dedicated server. Connect it with a WHM root token or a DirectAdmin admin login key, or add it as a shared hosting or reseller server instead.”

If your billing system has a root entry and reseller entries for the same machine (same IP address or hostname), you do not need to sort them out. The root entry becomes the Server (full access) and the reseller entries become its reseller accounts on this server, in whatever order they arrive. A reseller entry with no root entry for its machine shows as Reseller server (limited access), and Panelbot never offers the agent there: only the server’s own host can do root-level work on it. DirectAdmin follows the same rules: an admin login key is the root entry, and a reseller or user login key is a reseller entry. Server types explained covers each type.

A reseller login that is missing some WHM privileges still connects. The panelbot token then gets only what that login has, and the server’s details show Narrower than expected with the privileges it could not grant. Add them to that login in WHM (or DirectAdmin) and save the server again in your billing system, or leave it narrow on purpose.

You know this worked when the server shows Connected and its capability list is filled in. If it does not appear, confirm the hook or plugin was installed in the right place and that the server exists in your billing portal. If it shows Could not connect, the Billing server scan shows the reason the billing file reported.

What Panelbot can and cannot touch, shown to you

When a server connects, Panelbot checks what the credential you granted actually allows and shows you the result before the first customer chat. It is a live list generated from your server, not a promise from us.

On a cPanel/WHM server, the restricted panelbot token the connector mints carries exactly these privileges, nothing more:

• Account Summary
• List Accounts
• View Account Bandwidth Usage
• List Packages
• Basic System Information
• View Server Information
• View Server Status
• Perform cPanel API and UAPI functions through the WHM API
• Create User Session
• Manage DNS Records
• Suspend/Unsuspend Accounts
• Account Modification
• Upgrade/Downgrade Accounts
• Change Passwords
• ConfigServer Security & Firewall
• Basic WHM Functions

On DirectAdmin, the login key it mints carries a restricted list of reseller-level commands rather than these WHM labels, with login through the key turned off: CMD_API_SHOW_USERS, CMD_API_SHOW_USER_CONFIG, CMD_API_SHOW_USER_USAGE, CMD_API_SHOW_USER_DOMAINS, CMD_API_SELECT_USERS, CMD_API_MODIFY_USER, CMD_API_USER_PASSWD, CMD_API_PACKAGES_USER, CMD_API_SYSTEM_INFO, CMD_API_USER_BACKUP, CMD_API_SITE_BACKUP, CMD_API_ADDITIONAL_DOMAINS, CMD_API_DOMAIN, CMD_API_DOMAIN_POINTER, CMD_API_SUBDOMAINS, CMD_API_DNS_CONTROL, CMD_API_DATABASES, CMD_API_CRON_JOBS, CMD_API_EMAIL_AUTH, CMD_API_EMAIL_AUTORESPONDER, CMD_API_EMAIL_FORWARDERS, CMD_API_EMAIL_POP, CMD_API_POP, CMD_API_FTP, CMD_API_FTP_SHOW, CMD_API_SSL, and system-info. Admin-only commands and account creation are deliberately left out, and so is the login-keys group, so the key cannot manage keys.

Put plainly: Panelbot can reset an account’s password and open a support session on a customer’s behalf, but it never reads or stores an existing password, never touches your server’s root or admin password, and never sees your billing data through the server connection.

Worth being explicit about why the list stops there. Your billing portal usually holds the root credential for the server it just registered, and the connector does not send it (except the one-time agent-install hand-over described above). It mints this new restricted credential instead and Panelbot stores only that, so root stays where it was and the worst case of a mistake on our side is bounded by a list you can read and revoke on your own panel. The cost is that a few jobs, such as reading raw server logs, managing the firewall as root, or restarting a hung service, need root and are not available until you decide otherwise. With and without the agent sets out exactly which ones, and What the agent can and cannot do explains how the agent grants root as a fixed list of commands rather than an open credential.

The connector itself is not a secret. The hook or plugin is plain code that lives in your own portal, and you can read it. What it does is deliberately simple: register the server, mint that restricted token, send the hostname and token over an encrypted connection. Panelbot never displays a real API key, signing key, or credential anywhere in the dashboard; where one would appear, you see a placeholder.

Do I need to ask my host to whitelist anything?

Not to connect. Panelbot authenticates on the panel’s own API port, and a successful login does not count against the panel’s brute-force protection. You do not need an IP allowlist, and you do not need to ask an upstream host for one. Keep the credential valid and Panelbot keeps working.

Unblocking a customer’s IP in CSF or Imunify360 without the agent is not available today; IP unblocks run through the optional agent. See Reseller, VPS, and dedicated support.

Connect by hand instead

If you would rather not go through the billing portal, or the server is not one your portal knows about, create the panel credential yourself. On the connect page (Servers, then Connect server), open More options, find I’ll create the panel token myself, and choose Show the checklist and the form.

First create the credential on the panel, following the checklist for your panel:

• cPanel/WHM. In WHM, open Development > Manage API Tokens > Generate Token, name it panelbot, untick everything, then tick exactly the privileges listed above in What Panelbot can and cannot touch, shown to you. The checklist has a copy button for them. Do not tick Everything unless you mean to give root shell access: a root token with Everything is used as it is, and the connector will not replace it with a restricted one.
• DirectAdmin. Open Login Keys and create a key named panelbot with login off, no expiry, and exactly the allowed commands listed above.

Then fill in the form:

• Hostname. The server’s hostname.
• Port. The panel’s API port, 2087 for cPanel/WHM and 2222 for DirectAdmin by default.
• Control panel. cPanel/WHM or DirectAdmin.
• Credential. What kind of credential you are pasting. On cPanel: Reseller WHM API token or Root WHM API token. On DirectAdmin: DirectAdmin login key or DirectAdmin reseller login key.
• Server role. Shared hosting or reseller server or VPS or dedicated server. This decides the command set available on the server. Server types explained explains the difference. VPS or dedicated server needs a root WHM token or a DirectAdmin admin login key; a reseller credential is refused for it.
• Panel username. The user the credential belongs to. Leave it empty for a root WHM token, where root is implied.
• API token / login key. The secret itself. It is write-only: encrypted at rest, never shown again, and never logged.

Choose Verify and connect. Panelbot checks the credential straight away and fills in the capability list, exactly as it does for a server connected from billing. A reseller user is fine; a root or admin user reaches more. Billing IDs and reseller accounts are not part of this form; set them afterwards with Edit server on the Servers page, or with the billing scan below.

How the panel type is confirmed

You pick a Control panel when connecting a server, but Panelbot does not take your word as final. The first calls over the credential confirm which panel is really there, and the confirmed panel shows on the server’s detail view as Panel detected. So the panel is both declared by you and verified against the server.

Map your fleet from billing

The Billing server scan shows every server entry in your billing system and lets you get their roles right. From the Billing page choose Scan servers, or from the Servers page choose Sync from billing. Panelbot reads your connected portal and lists every server entry it finds. Entries that share an IP address or a hostname are grouped together, because they are the same physical server. If you ever need fresh data, Re-scan pulls it again.

Each entry also shows what the billing file reported for it, rather than a guess:

• Server (full access) or Reseller account: the kind of login your billing system stores for that entry.
• Could not connect: followed by the reason, when the billing file could not connect that entry.
• Not reported yet - install the billing file: the billing file has not reported this entry yet. Install it (or upload your newest download) and wait for the next billing cron run.

For each entry you set an action:

• Server (full access). The physical server itself (shared hosting or reseller). Some risky actions are blocked to protect every customer on it.
• Reseller account on this server. A reseller account on that same physical server. Choose which server it lives on with the Pick its server menu. No separate connection or agent is needed; commands run through that server.
• VPS or dedicated server. One customer’s own server. Enter its billing service ID in the field that appears so Panelbot can find it.
• Skip. Ignore this billing entry. No server is created or updated for it.

Panelbot suggests an action for each entry, and the counts at the top update as you go. Choose Save mapping when you are done. This updates servers already in Panelbot and links reseller accounts to their server. It does not add new cPanel or DirectAdmin servers: the billing file connects those, and the save message tells you how many it left for the billing file. It does not delete any Panelbot servers, so you can safely re-run the scan as your fleet changes. If a reseller account has no server to link to, Panelbot stops you and asks you to set one entry in its group to Server (full access), or to pick a server for each reseller account, first.

What the Servers page shows you

The Servers page is your at-a-glance view of every machine Panelbot works with. For each one you can see:

• Whether the server is reachable, shown as Online, Offline, or Pending.
• The confirmed panel and the capability list for the credential you granted.
• Basic health such as disk and load, where the credential can read it.
• The server’s detail view, where you manage its credential, review its panel details, adjust its reseller accounts, and, if you ever choose to, enroll the optional agent.

Disconnecting a server

On the connect page, open the server’s Show details and choose Disconnect to stop Panelbot from using its credential. What happens next depends on how the credential got there:

• Connected through the WHMCS/Blesta connector (the usual path). Disconnect removes the server from Panelbot right away. It does not delete the token on your panel, because your billing system owns that token’s lifecycle and will recreate it the next time the connector runs. To stop it being recreated, uninstall the connector from your billing portal.
• Connected with a credential you provided by hand. Disconnect removes it from Panelbot, and Panelbot also tries to revoke the token on the panel for you. That attempt is best effort, so finish by deleting it on the panel side yourself: in WHM under Development > Manage API Tokens, or in DirectAdmin under Login Keys. Look for a token or key named panelbot.

Either way, Panelbot stops using the credential the moment you disconnect.

If a server does not connect

• The credential is refused. Confirm the token or login key is for the right server and the right user, and that it has not been revoked on the panel side. Generate a fresh one and reconnect.
• The capability list is shorter than you expected. The credential is a reseller user, or a root token with a narrow set of permissions. If the server’s details show Narrower than expected, they list what is missing. Widen it on the panel side and reconnect, or leave it narrow on purpose; Panelbot works within whatever you grant.
• The server shows Could not connect. Open the Billing server scan: the entry shows the reason the billing file reported. Fix that in your billing system or on the panel, then save the server again in your billing system.
• Empty scan results. Confirm billing is connected and that your portal has servers configured, then choose Re-scan.
• A reseller account will not save. Set one entry in its group to Server (full access), or pick a server for the reseller account, then save again.

More cases are in Troubleshooting your setup.

What is next

Now that your servers are connected, the next page explains the server types in depth: full access, reseller, and VPS or dedicated, how nesting appears, and how reseller accounts on a server work. Read Server types explained. If you have a job that the capability list says the credential cannot reach, Install the optional server agent covers when that makes sense and how to do it.

Related

• Server types explained for server types and reseller accounts on a server.
• Install the optional server agent for the jobs a panel credential cannot reach.
• With and without the agent for which capabilities the minted credential reaches and which need more.
• Security overview for what the scoped credential can and cannot do.
• Troubleshooting your setup if the credential is refused or the scan comes back empty.