Provider guide

For the company that runs the platform and sells hosting: the platform administrator (the top login, created when the panel is installed) and provider administrators (logins of a provider org). Everything in reseller.md (customers, packages, delegation, branding, logins, billing) works the same at provider level, and everything in customer.md works inside any account below you.

Status of this guide (2026-10-14). It describes the console and tools as built in the code today. Most of it is tested in the development sandbox only and has not been walked through in a browser on the development cluster. Several features need a panel-api flag that is off by default (operator.md section 3); where that matters it is said. PLANNED marks what is not built. Live status: FEATURE_MATRIX.md, CHECKPOINT.md.

1. Who can do what

Cluster-wide pages and actions are for the platform administrator only: Cluster, node details, Deployment & recovery, declared capacity, alert rules, the reconciliation policy, platform alerts, creating a site on a named node (site.place), the operator PHP settings (php.admin) and backup inspection. A provider administrator does not see them, even though its role lists some of these powers: they need a grant at the root of the tree, which only the platform's own logins have.

Providers always hold every delegated power (sub-resellers, packages, branding); the platform does not need to delegate them.

2. Providers (platform administrator)

Providers lists the provider orgs. Create provider (on that page or on the platform's own page): Name, First login username and Initial password (must be changed at first sign-in), and optional Limits, then Create. Resellers and customers are created inside a provider, by its administrators or by you from the provider's page.

On a provider's page you manage, as for any org below you: limits and usage, region, logins (add, suspend, reset password, remove two-factor), branding, suspension and deletion. See reseller.md sections 2, 5 and 6.

3. Cluster and nodes (platform administrator)

Cluster shows: - Nodes: name, state (alive, suspect, dead), draining flag, last heartbeat, agent restarts and reconnects, location and roles. The state is as of the controller's last write of its node records, not now. Capacity per node is not reported by nodes. - Node metrics and History (CPU, memory, disk and more, when metrics sampling is on). - Links to Alerts and Alert rules. - Declared capacity (section 6).

If the page says "Node state unavailable", panel-api was started without access to the controller's node records (-controller-state or -etcd-endpoints).

Click a node for its page (/cluster/nodes/NAME): controller record and liveness, how old the records are, location and roles, boot ID, the controller role (leader or not, from the leadership lease, when reconciliation reads it), the latest metrics snapshot (CPU, load, memory, root filesystem, uptime, network counters since boot), history charts and open alerts on the node. Network history is not collected.

Node labels and draining are set on the command line by the operator, not in the console: panel-controller label -node N [-logical-region R] [-physical-region P] [-zone Z] [-cell C] [-roles web,db,...] and panel-controller drain / undrain. A drained node gets no new sites. The relocation plan of a node (GET /v1/cluster/nodes/{node}/relocation-plan) is read-only advice; moving sites between nodes is PLANNED.

4. Placement: creating a site on another node (platform administrator)

Normally a new site runs on the panel's own hosting node. With the site.place power, Websites > Add a website (on a customer's Websites page) shows a Node choice: "This panel's hosting node" or one of the nodes listed "(created by its agent)". Only nodes that are alive, not draining and have the web role are listed.

The site is checked exactly like a local one (domain unused on the platform, every quota on the way up), recorded as an agent site on that node and created by that node's agent. If the node refuses or fails, the site is shown as failed and keeps its quota until deleted. The API equivalent is POST /v1/orgs/{id}/sites with "node".

Status: IMPLEMENTED and tested through a real agent in the sandbox. On the development cluster no node runs the agent in execute mode and panel-api has no node endpoint yet (node03 activation stages E to H, operator.md section 6), so no site can be created on another node there yet.

Region rules (preferred and required region per org or package) are recorded and shown, and placement advice honours them; see reseller.md section 2.

Scheduled placement (option, off by default). With panel-api serve -placement scheduled the platform, not the person adding the site, chooses the node for a website added without a node. The Node choice then starts with "Chosen by the scheduler", followed by this panel's hosting node and the other nodes; customers and resellers see a note that the platform chooses. The scheduler takes the least loaded node that is alive, not draining, has the web role, passed its hosting-role preflight with the site's PHP version installed (the file named by -placement-node-facts, one entry per node: {"nodes":[{"node":"node03","preflight_passed":true, "checked_at":"2026-10-14T09:00:00Z","php_versions":["8.3"]}]}, written by the operator's preflight run; older than 7 days does not count), and lies in the account's required region. Another node also needs the node endpoint (-node-api-listen) and an agent that pulled within the last 2 minutes. If the hosting node wins the site is created locally as before; if another node wins it is created by that node's agent as in this section, without the site.place power. If no node qualifies, the website is not created: you see each node's reason, a customer sees only that no node can take it (and the required region when that is why). The reason for every placement is on GET /v1/sites/{id}/placement. Status: IMPLEMENTED in code and sandbox tests only; not enabled on the development cluster, where no node writes preflight facts and no agent pulls yet.

5. Alerts and alert rules

Alerts exist only when metrics sampling is on (panel-api serve -metrics-interval 60s). - Alerts shows node, cluster and database-server alerts as well as tenant alerts. Filter by Severity and On; tabs Open, Resolved, All, Rules. Open an alert for its chart, event history and related alerts. Acknowledge or Resolve with an optional note. - Alerts > Rules: each rule's condition, "for" time, re-open window, severity and state. Change RULE: Threshold, For (seconds), Re-open window (seconds), Severity (warning or critical), Enabled, or Restore the built-in values instead; Save rule. The next sample applies it. - Alerts are delivered to webhooks (event types alert.fired, alert.resolved); delivery by email is PLANNED.

6. Capacity

Cluster > Declared capacity > Declare capacity: CPU (% of one core, summed over the cluster), Memory (MB), Disk (MB) and Overcommit (%, 100 = none), then Save. The table shows declared, allowed with overcommit, and committed (the sum of every customer account's CPU, memory and disk caps). New accounts, limits and packages that would exceed the allowed amount are refused. Clear the declaration instead turns the check off. Capacity is declared by you, not measured from the nodes.

7. Reconciliation policy (platform administrator)

Reconciliation compares each site's configuration on the node with the panel's record. It runs only when panel-api is started with -reconcile dry-run (observe and report) or -reconcile on (also remediate opted-in sites under the leader's grant).

On a site's page, Configuration and reconciliation shows the status (in sync, drift, missing, ...), the policy, the generations of panel and node, the configuration digest, findings and recent events. To change the policy: choose Observe or Remediate, Review policy change, then confirm with Set policy to .... With remediate, managed configuration (web server, PHP-FPM pool, suspension, cron) that drifts is rewritten to match the panel, and changes made on the node by hand are overwritten.

The cluster summary and "run a pass now" are API only: GET /v1/reconcile, POST /v1/reconcile/run. Today it covers sites on panel-api's own hosting node only; other nodes are PLANNED.

8. Operator PHP settings

On a site's PHP settings tab you also see Operator settings: allow_url_fopen and Extra disabled functions (comma-separated, at most 64). Nothing inside the website can override them.

9. Backups at platform level

In addition to what customers can do (customer.md section 6), the platform administrator can: - restore a restore point into another account (field "Into account" in the restore form); - Extract for inspection (24 h): unpack a restore point into a root-only directory on the node (TLS keys are not extracted); listed under Inspections with Remove now; - clean up leftovers and read recovery metrics over the API (POST /v1/backups/cleanup, GET /v1/backups/metrics); - bring back a deleted site from the archive the node made when it was deleted: Deployment & recovery > Deleted-site archives lists the archives on the panel's hosting node (site id, when, file, SHA-256), newest first; Restore site id on a site's newest archive restores it (API: GET /v1/site-archives, POST /v1/sites/{id}/restore). A site the panel still holds shows "site exists" and cannot be restored over. The restored site serves again, but the panel does not hold its record again: it is not listed under its account and charges no quota. Archives of sites on other nodes are not listed.

Sites on another node (section 4) are backed up on that node by its panel-host serve -backup-dir (customer.md section 6, "Websites on another node"); their schedules run in this panel's scheduler and each due backup is an operation for the node. Inspection of such a restore point is not offered yet, and cleanup and recovery metrics cover the panel's own node only. A node without -backup-dir refuses backups of its sites.

Restore points are on the same node as the data. Off-site copies are on hold (Product Owner decision) and not built.

10. Billing of providers, resellers and customers

The rules are those of reseller.md section 8; each level bills the orgs directly below it: - the platform's Billing page bills providers; - a provider's Billing page bills its resellers and its direct customers; - a reseller bills its own customers.

So a provider bills its resellers by creating plans on its Billing page and assigning them on each reseller's billing page. The reseller's statement shows what it is billed and its margin. Statements need hourly metering (panel-api serve -billing-meter); without it the pages say "Usage is not being metered". Taxes, payments and a WHMCS module are PLANNED (not built); hand the CSV or JSON exports to your billing system.

11. Required two-factor sign-in

The operator starts panel-api with -require-2fa-roles, a comma-separated list of roles from platform_admin, provider_admin, reseller, account_owner, read_only (for example -require-2fa-roles platform_admin,provider_admin,reseller). A login of such a role can still sign in, but until it enrols it can only read its account, set up two-factor sign-in, change its password, list or revoke its API tokens and sign out; the console sends it to Your account. The setting is per role for the whole platform; per org it is PLANNED. WebAuthn (security keys) is PLANNED.

12. cPanel migration

Today (IMPLEMENTED): a dry run. On a machine with the archive:

panelctl import-cpanel -archive cpmove-USER.tar.gz [-json]

It reads a cPanel pkgacct archive without extracting or executing anything and prints the migration plan (the account with suggested limits, sites, databases, cron, DNS zones and more) and a compatibility report: each item is migrated, migrated with changes, not migrated, refused as unsafe, or unknown. Exit status 0 = read and safe, 3 = read but holds refused entries, 1 = could not be read within the safety limits, 2 = usage error. It has been tested on synthetic archives, not yet on one made by a real cPanel server.

IMPLEMENTED (sandbox-tested, not yet run on a real archive): the import itself (backlog P6, ADR-0034), for platform administrators, provider administrators and resellers (migration.run) on a customer account: 1. Open the account; under Migration choose Import a cPanel account and upload the cpmove-USER.tar.gz archive. The panel reads it under the same safety rules as the dry run and shows the plan, the compatibility report and the quota check; nothing is created yet. An unsafe archive is refused and its copy deleted. 2. Confirm and run. The panel creates, in order: DNS zones, websites (with aliases, PHP and cron), certificates, databases and users (new passwords, shown once to you after the run, never stored), copies each website's files as the website's own user, and loads MariaDB dumps as the database's own account after checking every statement. The page shows each item's progress and outcome. 3. A run that stopped can be run again: what was done is not repeated, and anything that existed before the import is left untouched. When the run is done the uploaded archive is deleted. Not yet: PostgreSQL dumps, file copy for a website on another node, email (backlog P6c). From the command line: panelctl import-cpanel -archive F -account ID -api URL -token-file F [-run -yes].

13. Audit and other pages

• Audit log: the platform administrator sees every event; the hash chain check covers the whole log.
• Deployment & recovery: the running panel version and when the controller last wrote node records; for the platform administrator also the link to Deleted-site archives (section 9). Failover, backup and drill results are not reported to this page yet.
• Database insight and Logs & monitoring: overview pages not built yet; per-database reports and per-site logs are on the database and site pages.

14. Not available yet (PLANNED)

Email hosting, an installer for new servers, automatic site failover and file replication between nodes (no website HA), off-site backups, control-plane database HA, moving sites between nodes, impersonation of a customer (no role holds a permission for it; backlog P19), hard disk and inode quota enforcement on the current nodes (the panel measures usage and enforces quotas soft: it refuses its own writes, uploads, imports and new sites at the limit and raises alerts, but PHP, SFTP and cron writes are not stopped until a node has filesystem project quotas; ADR-0050, merged in c43dae5, not yet released to the development cluster), PostgreSQL dumps in the cPanel import, DNS served from the development cluster (PowerDNS is not deployed).