BorealHost

Rotate the current email-only key with overlap, preserving scope and expiry.

Rotate an API key, optionally keeping the old key valid for up to 1,440 minutes. Creates a new key with the same name, scopes, and rate limits. The new key is returned once — store it immediately. Requires: API key with write scope. Args: key_id: UUID of the API key to rotate (get from whoami()) Returns: {"api_key": "bh_...", "key_id": "uuid", "prefix": "bh_...", "scopes": ["read", "write"], "message": "Key rotated. Store securely."} Expiry and all restrictions are preserved. Without a grace period the old key stops working immediately.

Run a ClamAV malware scan on a site's container. Scans the web root (or specified path) for malware, viruses, and trojans. ClamAV is installed automatically if not present. Excludes node_modules, vendor, .git, and cache directories. May take up to 5 minutes for large sites. Requires: API key with write scope. Args: slug: Site identifier path: Directory to scan (default: /var/www/html) Returns: {"infected_files": [{"path": "/var/www/html/shell.php", "threat": "Php.Malware.Agent"}], "scanned_count": 1234, "infected_count": 1, "scan_time_s": 45.2}

Change a site's hosting plan (upgrade or downgrade). Requires: API key with admin scope. Best practice: create a snapshot before downgrading. Args: slug: Site identifier new_plan: Target plan slug (e.g. "site_pro", "site_managed"). Call list_plans() to see available plans. Returns: {"success": true, "old_plan": "site_starter", "new_plan": "site_pro", "message": "Plan changed successfully"} Errors: NOT_FOUND: Unknown slug VALIDATION_ERROR: Invalid plan slug or same plan

Schedule a snapshot for future execution. Requires: API key with write scope. Max 3 pending schedules per site. Args: slug: Site identifier scheduled_at: ISO 8601 datetime (must be in the future) description: Optional description (max 200 chars) Returns: {"id": "uuid", "scheduled_at": "iso8601", "status": "scheduled"} Errors: VALIDATION_ERROR: Invalid datetime, not in future, or too many pending

Check domain availability and get pricing. Requires: API key with read scope. Args: domain: Full domain name (e.g. "example.com", "mybiz.ca") Returns: {"domain": "example.com", "available": true, "registration_estimate_cad": "15.99", "currency": "CAD", "price_cad_includes_privacy": false, "total_cad": null, "quote_required": true} Note: .ca domains require ca_legal_type when registering.

Set your BorealHost API key for this session. Call this if you already have an API key (from checkout completion, the BorealHost panel, or a container claim). All subsequent tool calls will use this key for authentication. Args: api_key: Your BorealHost API key (format: bh_<48 hex chars>) Returns: {"success": true, "message": "API key set for this session", "key_prefix": "bh_..."}

Set the backup retention policy for a VPS site. Storage is billed on real stored bytes, so deeper history costs the customer, not the platform. Values are clamped to platform bounds; the response reports what was actually stored. Pass -1 to leave a knob unchanged, or reset=true to restore defaults. Requires: API key with write scope. Returns: {"site", "retention": {...}}

Set what a registered domain points at — a site, someone else's nameservers, our DNS with no site, or a redirect to another URL. Use this to park a domain, hand it to an external host, or forward it. Switching modes tears down the previous one (a forwarded domain that becomes a site domain loses its redirect, and vice versa). Requires: API key with write scope. Args: domain_name: Full domain name (e.g. "example.com") usage_mode: "site" — link it to a hosted site (needs site_slug); "external_ns" — delegate to the customer's own nameservers (needs nameservers), we stop managing its DNS entirely; "dns_only" — our nameservers, records edited by hand, nothing served; "forward" — our nameservers plus an HTTP redirect to forward_url (needs forward_url) site_slug: Site to link to, when usage_mode="site" nameservers: Ordered list of 2–6 nameserver hostnames, when usage_mode="external_ns" forward_url: Redirect target, when usage_mode="forward" forward_type: "301" permanent (default) or "302" temporary forward_include_path: Append the visitor's path to the target (default: True) Returns: {"domain": "example.com", "usage_mode": "forward", "forward_url": "https://example.org", "configuration": {"dns": true, "nginx": true, "ssl": false, ...}} For forward mode, ssl=false usually just means DNS has not propagated yet — call this tool again a few minutes later to finish the cert. Errors: NOT_FOUND: Domain or site not found VALIDATION_ERROR: Bad nameserver hostname, bad redirect URL, missing site_slug, or a self-referential redirect

Enable or disable the HTTP→HTTPS redirect for a site. Requires: API key with write scope. Returns: {"site", "force_https": true|false, "message"}

Replace the complete alias list idempotently (maximum 2,000).

Set custom nginx config on the BorealHost host proxy — WebSocket, timeouts, headers. Use this when configuring your container's own nginx is not enough because something in front of it is interfering. The host proxy sits between the internet and your container, and by default its catch-all `location /` does not do anything special per-site. WEBSOCKETS: if your WebSocket endpoint returns 400 through your domain but upgrades correctly (101) when tested inside your container, the Upgrade header is being dropped in front of you. Add a location block that relays it: location ^~ /your/ws/path/ { proxy_pass <your site's existing upstream>; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 3600; proxy_send_timeout 3600; error_page 502 503 504 =502; } When testing with curl, force HTTP/1.1 (curl --http1.1). A WebSocket handshake uses the Upgrade header, which is invalid in HTTP/2 — curl negotiates h2 with a CDN by default and the edge answers 400, which looks exactly like the bug you are trying to fix. This config lives OUTSIDE the generated vhost, so it survives domain re-linking, autoconfig, plan changes and reprovisioning. Sending "" clears it. Bounds — the file is parsed by a root process on a machine shared with BorealHost infrastructure, so only per-site proxy directives are accepted: location, proxy_pass, proxy_set_header, proxy_http_version, proxy_*_timeout, proxy_buffering, client_max_body_size, add_header, error_page, expires, gzip. `root`, `alias`, `include`, `access_log`, `error_log`, `server` and `upstream` are refused, and proxy_pass must target your own site's existing upstream. A rejection names the directive and why. The config is validated with `nginx -t` before it is applied and rolled back automatically if it does not pass, so a mistake cannot take your site down. Requires: API key with write scope. Args: do…

Change what a site's docroot IS, without deleting anything. Types: wordpress WordPress, PHP and a database (the default) php PHP and a database, no WordPress php-nodb PHP, no database static-site HTML/CSS/JS only, no PHP and no database ⚠ NON-DESTRUCTIVE. Existing files stay on disk and existing databases are not dropped. They remain the customer's data and keep counting against their plan's quota — this changes how the site is SERVED, not what it holds. Converting back later finds everything where it was. ⚠ Moving to a type without PHP does not merely stop executing .php — it stops serving them. The vhost returns 404 for php/phtml, because falling through to the static handler would return the file's SOURCE, and a docroot converted from WordPress still contains wp-config.php with the database password in it. Shared hosting only. On a VPS the whole container is the customer's and they reconfigure it with the tools inside it. Requires: API key with write scope. Args: slug: Site identifier site_type: One of the four values above Returns: {"from": "wordpress", "to": "static-site", "database_created": false, "placeholder_seeded": false, "pool_removed": true} `placeholder_seeded` is true only when the docroot was EMPTY — an existing site's content is never overwritten. Errors: VALIDATION_ERROR: Unknown type, or the site is not on shared hosting NOT_FOUND: Unknown slug or not reachable by this account

Enable business email (hosted mailboxes + webmail) on a domain. Creates the hosted-email domain, sets up outbound authentication (DKIM/SPF), and auto-configures MX/SPF DNS when the zone is hosted by BorealHost. Mailboxes are billed per-mailbox on the site subscription. Requires: API key with write scope. Returns: {"configured": true, "domain", "dns_auto_configured", "message"}

Queue a checkpoint snapshot without detaching — before a risky change. ASYNCHRONOUS. Returns immediately with state "snapshotting"; poll get_compute_volume until it is back to "attached" (done) or "error". Named systemd units are stopped for the capture so the snapshot is application-consistent (a live database directory copied mid-write is not reliably restorable). The worker restarts nothing — reboot or start them yourself afterwards. Requires: API key with write scope. Args: volume_id: A volume in state "attached" quiesce_units: Services to stop during capture, e.g. ["ollama.service", "postgresql.service"] Returns: Volume dict with state "snapshotting". Poll for the outcome.

Get SSL certificate information for a site. Returns certificate details, expiry date, and issuer. Requires: API key with read scope. Args: slug: Site identifier Returns: {"issuer": "Let's Encrypt", "domain": "example.com", "expires_at": "iso8601", "days_remaining": 60, "force_https": true}

Force SSL certificate renewal via certbot. Requires: API key with write scope. Args: slug: Site identifier Returns: {"renewed": true, "expires_at": "iso8601"}

Start a stopped compute instance. Requires: API key with write scope.

Stop a compute instance. WARNING: hourly billing continues while stopped. Use terminate_compute_instance to stop the charges permanently. Requires: API key with write scope.

Switch the active PHP version for a site. Requires: API key with write scope. Args: slug: Site identifier version: Target PHP version (e.g. "8.3", "8.2", "8.1") Returns: {"version": "8.3", "result": {...}}

Permanently terminate a compute instance — this stops hourly billing. The instance and its disk are destroyed and cannot be recovered. Copy any results off the instance before terminating. Requires: API key with write scope. Returns: Final instance dict with state "terminated" and total accrued_cad.

Send a test event to a webhook endpoint (async). Poll list_webhooks afterwards for last_status. Requires: API key with write scope. Returns: {"id", "message"}

Enable or disable an AI module on a site. The module must be in the plan's available module list. Requires: API key with write scope. Args: slug: Site identifier module_name: Module to toggle. Available modules: "chatbot" (AI chat widget), "seo" (SEO optimization), "translation" (content translation), "content" (AI content generation) Returns: {"module": "chatbot", "enabled": true, "message": "Module enabled"} Errors: NOT_FOUND: Unknown slug or module not in plan VALIDATION_ERROR: Invalid module name

Prepare a domain to transfer to another registrar. Unlocks the domain and emails the EPP/auth code to the registrant contact on file (BorealHost never sees the code). The domain keeps working here until the transfer completes. Requires: API key with write scope. Returns: {"domain", "unlocked": true, "auth_code_emailed": true, "message"}

Update account profile fields (email, language, name). Requires: API key with write scope. Only provided (non-empty) fields are updated. Args: email: New email address language: Language preference — "fr" (French) or "en" (English) first_name: First name last_name: Last name Returns: {"success": true, "account": {"email": "...", "language": "fr", "first_name": "...", "last_name": "..."}} Errors: VALIDATION_ERROR: Invalid email format or language code

Set buyer email and desired site slug on a checkout session. The checkout must be in "not_ready" status. Setting requested_slug transitions status to "ready" (required before completing). Args: checkout_id: Checkout session ID from create_checkout buyer_email: Optional email — if omitted, a synthetic agent identity (agent-{uuid}@api.borealhost.ai) is created at completion requested_slug: Desired site identifier. Must be 3-50 chars, lowercase alphanumeric + hyphens, cannot start/end with hyphen. Must be globally unique. site_type: What the docroot should serve — wordpress (default), php, php-nodb or static-site. ⚠ Set it HERE: the checkout locks once buyer info is set, so choosing later means provisioning a WordPress you then convert away from, abandoning its tree in the docroot and paying a minute of provisioning for nothing. Returns: {"id": "uuid", "sku": "...", "plan_slug": "...", "billing_period": "monthly", "status": "ready", "buyer_email": "...", "requested_slug": "my-site", "created_at": "iso8601"} Errors: VALIDATION_ERROR: Invalid slug format or slug already taken FORBIDDEN: Missing checkout_secret NOT_FOUND: Unknown checkout_id

Set mailbox_limit, alias_limit, quota_gb, smtp_sent_limit, services or language.

Set display_name, quota_gb, smtp_sent_limit, label, services or suspended. Suspension disables client access and outbound SMTP while preserving receipt.

Upload a base64-encoded file to a site's container. Use this for binary files (images, archives, fonts, etc.). For text files, prefer write_file(). Requires: API key with write scope. Args: slug: Site identifier path: Relative path including filename (e.g. "images/logo.png") content_b64: Base64-encoded file content Returns: {"success": true, "path": "images/logo.png", "size": 45678} Errors: VALIDATION_ERROR: Invalid base64 encoding FORBIDDEN: Protected system path

Install your own SSL certificate for a site's domain. The certificate must be a PEM fullchain (leaf + intermediates) and the key unencrypted PEM. Validated (parse, key match, domain coverage, expiry) before nginx is touched; nginx config is tested before reload. Requires: API key with write scope. Returns: {"site", "domain", "server_names", "installed": true, "ssl_active": true, "not_after"}

Check the current API key's account info, scopes, and site count. Requires: BOREALHOST_API_KEY env var (read scope). Returns: {"user": {"id": "uuid", "email": "...", "date_joined": "iso8601"}, "api_key": {"id": "uuid", "name": "...", "prefix": "bh_...", "scopes": ["read", "write"], "created_at": "iso8601"}, "account": {"sites": 2, "active_subscriptions": 1}} Errors: UNAUTHORIZED: Missing or invalid API key

Check for available WordPress core, plugin, and theme updates. Requires: API key with read scope. Args: slug: Site identifier Returns: {"core": {"current": "6.5", "update": "6.6"}, "plugins": [{"name": "...", "current": "1.0", "new": "1.1"}], "themes": [...]}

Update WordPress core, all plugins, and all themes. Runs all updates in sequence. May take up to 2 minutes. Requires: API key with write scope. Args: slug: Site identifier Returns: {"core": {...}, "plugins": [...], "themes": [...]}

Write or overwrite a text file in a site's container. Creates parent directories if they don't exist. Requires: API key with write scope. Args: slug: Site identifier path: Relative path to the file content: File content as a UTF-8 string Returns: {"success": true, "path": "...", "size": 1234} Errors: NOT_FOUND: Unknown slug FORBIDDEN: Protected system path