BorealHost

Add a cron job to a site. Requires: API key with write scope. Args: slug: Site identifier schedule: Cron schedule (e.g. "*/5 * * * *", "0 2 * * *") command: Command to execute Returns: {"added": true, "result": {...}}

Add a DNS record to a domain. Requires: API key with write scope. Args: domain_name: Full domain name (e.g. "example.com") record_type: "A", "AAAA", "CNAME", "MX", "TXT", or "SRV" value: Record value (e.g. "1.2.3.4" for A, "mail.example.com" for MX) subdomain: Subdomain part (e.g. "www", "mail"). Empty for apex domain. ttl: Time to live in seconds (default: 3600) priority: MX priority (required for MX records) Returns: {"success": true, "record": {"id": "...", "type": "A", "subdomain": "www", "value": "1.2.3.4", "ttl": 3600}} Errors: VALIDATION_ERROR: Missing value, invalid record type NOT_FOUND: Domain not found

Add an IP firewall rule (allow or deny) and reload Nginx. Supports IPv4, IPv6, and CIDR notation. Max 100 rules per site. If a rule already exists for the IP, the action is updated. Requires: API key with write scope. Args: slug: Site identifier ip: IP address or CIDR (e.g. "1.2.3.4", "10.0.0.0/8", "2001:db8::/32") action: "deny" (block) or "allow" (whitelist). Default: "deny" Returns: {"added": true, "ip": "1.2.3.4", "action": "deny"}

Inject your SSH public key into a site's container for direct SSH access. The key is appended to /home/admin/.ssh/authorized_keys. Only available for VPS/dedicated plans. Requires: API key with write scope. Args: slug: Site identifier public_key: SSH public key string. Supported types: ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256/384/521 Returns: {"success": true, "message": "SSH key added", "ssh_command": "ssh [email protected]"} Errors: VALIDATION_ERROR: Invalid or unsupported key format FORBIDDEN: Plan does not support SSH

Turn an instance you are ALREADY running into a persistent volume. Use this when you launched something, set it up, and then decided you want to keep it. Nothing reboots and no data moves — the machine you have becomes the volume, and you can detach it afterwards to stop paying for compute while keeping the machine. Beats creating a volume and rebuilding. Only instances launched with an ssh_public_key qualify. One launched with your own user_data carries only your key, and a key cannot be added to a machine we cannot already log into — check "managed_ssh" on the instance. Requires: API key with write scope, and an active subscription. Args: instance_id: A running lsw.* instance you own name: Label for the volume (defaults to the instance name) Returns: Volume dict with state "attached", wrapping that same instance. No snapshot exists yet — the first one is taken on detach or snapshot. Errors: CONFLICT: Not running, already a volume, BorealHost Metal, or launched without BorealHost management access

Restore a detached volume onto a fresh instance — optionally a new type. Pass a different instance_type to move the same machine to different hardware: this is the closest thing to changing instance type that the provider allows, since it has no resize API at all. The restore runs at first boot and the machine reboots into itself, so the instance answers SSH BEFORE it is ready. Poll get_compute_volume and give it a few minutes (measured: ~6 min for a 10 GB GPU machine end to end). The machine keeps its SSH host keys, so your client will not warn about a changed host identity. Requires: API key with write scope. Args: volume_id: A volume in state "detached" ssh_public_key: Required — installed via cloud-init at boot instance_type: Defaults to the type it last ran on root_disk_size: GB. May grow, never shrink below the volume's size. Returns: Volume dict with state "attached" and a new instance. Errors: CONFLICT: Volume is not detached, or has no snapshot yet

Flush all caches (Redis + WP object cache). Requires: API key with write scope. Args: slug: Site identifier Returns: {"flushed": true}

Get cache status (Redis, WP object cache, hit rates). Requires: API key with read scope. Args: slug: Site identifier Returns: {"redis_running": true, "object_cache_enabled": true, "hit_rate": 0.95, "memory_used_mb": 12}

Enable or disable the WordPress object cache. Requires: API key with write scope. Args: slug: Site identifier enable: true to enable, false to disable Returns: {"enabled": true}

Cancel a scheduled snapshot. Requires: API key with write scope. Args: slug: Site identifier schedule_id: UUID of the scheduled snapshot to cancel Returns: {"success": true, "message": "Scheduled snapshot cancelled"} Errors: NOT_FOUND: Schedule not found or already executed

Claim an API key using a claim token from the container. After calling request_api_key(), read the claim token from ~/.borealhost/.claim_token on your container and pass it here. The token is single-use — once claimed, it cannot be used again. The API key is automatically activated for this MCP session. Args: claim_token: The claim token string read from the container file Returns: {"api_key": "bh_...", "key_prefix": "bh_...", "site_slug": "my-site", "scopes": ["read", "write"], "message": "API key created and activated..."} Errors: VALIDATION_ERROR: Invalid, expired, or already-claimed token

Get Cloudflare proxy (CDN) status for a site. Shows whether traffic is routed through Cloudflare's CDN (orange cloud) or goes direct to origin (grey cloud / DNS-only). Requires: API key with read scope. Args: slug: Site identifier Returns: {"domain": "my-site.borealhost.ai", "has_record": true, "proxied": true, "ip": "1.2.3.4"}

Purge Cloudflare CDN cache for a site. Without urls: purges all cached content for the site's subdomain. With urls: purges only the specified URLs (max 30 per call). Requires: API key with write scope. Args: slug: Site identifier urls: Optional list of specific URLs to purge (e.g. ["https://my-site.borealhost.ai/style.css"]) Returns: {"purged": true, "scope": "host", "domain": "my-site.borealhost.ai"}

Enable or disable Cloudflare CDN proxy for a site. When enabled (orange cloud): traffic goes through Cloudflare's CDN, gets caching, DDoS protection, and SSL termination at the edge. When disabled (grey cloud): traffic goes directly to origin server. Requires: API key with write scope. Args: slug: Site identifier proxied: true to enable CDN proxy, false to disable Returns: {"domain": "my-site.borealhost.ai", "proxied": true, "ip": "1.2.3.4"}

Complete checkout with payment and start site provisioning. The checkout must be in "ready" status. Two payment methods: - "stripe_checkout" (default): Returns a short, chat-safe payment URL. **Present `payment_url` to the human — NOT `stripe_checkout_url`.** The raw Stripe URL has a required `#fragment` that chat UIs routinely strip when rendering markdown links, which causes Stripe to show "page not found". `payment_url` is a short BorealHost redirect that preserves the fragment via HTTP 302. Then poll get_checkout_status() until status becomes "completed". The API key appears in the first poll after payment (shown once, then cleared). - "stripe_payment_method": Charges a Stripe PaymentMethod directly. Requires payment_method_id. On success, returns the API key immediately. Args: checkout_id: Checkout session ID payment_method: "stripe_checkout" or "stripe_payment_method" payment_method_id: Stripe PaymentMethod ID (pm_...). Required only for "stripe_payment_method". Returns (stripe_checkout): {"id": "uuid", "status": "awaiting_payment", "payment_url": "https://borealhost.ai/pay/<id>/?s=<secret>", "stripe_checkout_url": "https://checkout.stripe.com/c/pay/...", "message": "Present payment_url to the human..."} Returns (stripe_payment_method): {"id": "uuid", "status": "completed", "api_key": "bh_...", "api_key_message": "Store this API key securely...", "subscription_id": "uuid", "provisioning_job_id": "uuid"} Errors: VALIDATION_ERROR: Missing payment_method_id for stripe_payment_method FORBIDDEN: Checkout not in "ready" status

Create an alert rule to monitor CPU, memory, or disk usage. When the metric crosses the threshold, a notification is sent via email and/or webhook. Max 10 rules per site. Requires: API key with write scope. Args: slug: Site identifier metric: "cpu", "memory", or "disk" (percentage-based) threshold: Threshold value 0-100 (e.g. 90 for 90%) operator: "gt" (greater than) or "lt" (less than). Default: "gt" severity: "warning" or "critical". Default: "warning" cooldown_minutes: Min minutes between repeated alerts. Default: 30 notify_email: Send email notification. Default: true notify_webhook: Optional webhook URL for POST notifications Returns: {"id": "uuid", "metric": "disk", "threshold": 90, ...}

Create a new API key with specified scopes. Cannot create keys with higher scopes than the current key. Site-scoped keys restrict access to a single site. Requires: API key with write scope. Args: name: Human-readable name for the key (1-100 chars) scopes: Comma-separated scopes. Options: "read", "read,write", "read,write,admin". Default: "read" site_slug: Optional — restrict the key to a single site. Omit for account-wide access. Returns: {"api_key": "bh_...", "key_id": "uuid", "prefix": "bh_...", "name": "My Key", "scopes": ["read", "write"], "message": "Store this API key securely — it will not be shown again."} Errors: VALIDATION_ERROR: Invalid name, scopes, or max 25 active keys FORBIDDEN: Cannot create keys with higher scopes than current key

Create a B2 cloud-backed snapshot (zero local disk, async). Streams container data directly to Backblaze B2 via restic. No local disk impact — billed separately at cost+5%. Runs in background — returns immediately with status "creating". Poll list_snapshots() to check when status becomes "completed". Only available for VPS plans. Requires: API key with write scope. Args: slug: Site identifier description: Optional description (max 200 chars) Returns: {"id": "uuid", "name": "...", "status": "creating", "storage_type": "b2", "message": "B2 cloud snapshot started. Poll list_snapshots()..."} Errors: VALIDATION_ERROR: Not a VPS plan or max snapshots reached

Create a manual backup (runs asynchronously). The backup starts in the background. Poll list_backups() to check status. Requires: API key with write scope. Args: slug: Site identifier Returns: {"id": "uuid", "status": "pending", "message": "Backup started. Poll list_backups() to check status."}

Start a new checkout session to purchase a hosting plan. No authentication needed. After creating, call update_checkout to set buyer info, then complete_checkout to pay. Args: sku: Plan SKU in format bh_{plan_slug}_{monthly|annual}. Examples: "bh_site_starter_monthly", "bh_site_pro_annual", "bh_site_managed_monthly", "bh_site_business_annual". Call list_plans() to discover all available plan slugs. Returns: {"id": "uuid", "sku": "bh_site_starter_monthly", "plan_slug": "site_starter", "billing_period": "monthly", "status": "not_ready", "buyer_email": "", "requested_slug": "", "created_at": "iso8601", "checkout_secret": "base64-token"} Errors: VALIDATION_ERROR: Invalid SKU format or unknown plan RATE_LIMITED: Max 10 checkouts per IP per hour

Create a persistent machine and boot its first instance. Start here, then set the machine up however you like (install packages, drivers, models). Everything you do becomes part of the volume the first time you detach or snapshot it. While attached you pay hourly compute; while detached you pay only for stored bytes (CA$0.03/GB/month). Stopping an instance does NOT save money on this provider — detaching is what stops the compute charge. Requires: API key with write scope, and an active subscription. Args: name: Label for the volume, e.g. "trainer" image_id: From list_compute_images, e.g. "UBUNTU_24_04_64BIT". Cannot change later — restores must land on the same OS. instance_type: From list_compute_types, e.g. "lsw.g6.xlarge". CAN change on every later attach. ssh_public_key: Required. Volume instances always boot via cloud-init, so this is the only way in. root_disk_size: GB. Defaults to the type's minimum (or 25). Returns: Volume dict with state "attached". Poll get_compute_volume until instance.state is "running" (~1-3 min). Errors: PAYMENT_REQUIRED: No active subscription LIMIT_EXCEEDED: Volume cap reached NOT_AVAILABLE: Volumes not enabled on this deployment

Create a directory 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 of the directory to create Returns: {"success": true, "path": "uploads/2024", "message": "Directory created"} Errors: NOT_FOUND: Unknown slug FORBIDDEN: Protected system path

Create an SFTP account on a site. The account is chrooted to /var/www and lands in home_dir. Password must be at least 8 characters. Username must be lowercase alphanumeric. Requires: API key with write scope. Args: slug: Site identifier username: SFTP username (lowercase, max 32 chars) password: Password (min 8 chars) home_dir: Landing directory inside /var/www. Leave empty to land at /var/www itself, which lists every site directory. Returns: {"success": true, "username": "sftpuser", "home_dir": "/wordpress", "protocol": "sftp"}

Create a local container snapshot (async). Runs in background — returns immediately with status "creating". Poll list_snapshots() to check when status becomes "completed" or "failed". Available for VPS, dedicated, and cloud plans (any plan with max_snapshots > 0). Local snapshots are stored on the host disk and count against disk quota. Requires: API key with write scope. Args: slug: Site identifier description: Optional description (max 200 chars) Returns: {"id": "uuid", "name": "snap-...", "status": "creating", "storage_type": "local", "message": "Snapshot started. Poll list_snapshots() to check status."} Errors: VALIDATION_ERROR: Max snapshots reached or insufficient disk quota

Search and replace in WordPress database (e.g. URL migration). Handles serialized data safely. Use dry_run=true first to preview changes. Requires: API key with write scope. Args: slug: Site identifier old: String to search for (e.g. "http://old-domain.com") new: Replacement string (e.g. "https://new-domain.com") dry_run: Preview only without making changes (default: true) Returns: {"replacements": 42, "tables_affected": 5, "dry_run": true}

Delete a site and schedule resource cleanup (7-day grace period). WARNING: This is destructive. The site will be inaccessible immediately but data is retained for 7 days before permanent deletion. Best practice: create a snapshot before decommissioning. Requires: API key with admin scope. Args: slug: Site identifier Returns: {"success": true, "message": "Site scheduled for deletion", "grace_period_days": 7} Errors: NOT_FOUND: Unknown slug

Permanently anonymize the account. Cancels subscriptions, deactivates keys. WARNING: This is irreversible. The account will be soft-deleted and all personal data anonymized. All sites will be decommissioned. Requires: API key with admin scope. Returns: {"success": true, "message": "Account anonymized"}

Delete an alert rule. Requires: API key with write scope. Args: slug: Site identifier rule_id: UUID of the alert rule to delete Returns: {"deleted": true, "id": "uuid"}

Permanently delete a volume and everything stored in it. Irreversible: the instance is released AND the stored data is purged from object storage, so billing genuinely stops. Refuses while an instance is live unless force=True, so a running machine's only copy cannot be destroyed by reflex. Requires: API key with admin scope. Returns: {"id", "state": "deleted"}

Delete a cron job by line number. Get line numbers from list_cron(). Requires: API key with write scope. Args: slug: Site identifier line_number: Line number of the cron entry to delete Returns: {"deleted": true}

Delete a DNS record from a domain. Requires: API key with write scope. Args: domain_name: Full domain name (e.g. "example.com") record_id: ID of the DNS record to delete (from list_domain_dns) Returns: {"success": true, "message": "DNS record deleted"} Errors: NOT_FOUND: Domain or record not found

Delete a file or directory from a site's container. Directories are deleted recursively. Protected system paths (e.g. /etc, /usr) cannot be deleted. Requires: API key with write scope. Args: slug: Site identifier path: Relative path to delete Returns: {"success": true, "path": "...", "message": "Deleted"} Errors: NOT_FOUND: Path doesn't exist FORBIDDEN: Protected system path

Delete a snapshot (local or B2). Requires: API key with write scope. Args: slug: Site identifier snapshot_id: UUID of the snapshot to delete Returns: {"success": true, "message": "Snapshot deleted"} Errors: NOT_FOUND: Snapshot not found

Trigger a deployment for a site. Requires: API key with write scope. This may take up to 60 seconds. Args: slug: Site identifier Returns: {"success": true, "message": "Deployment triggered"} Errors: NOT_FOUND: Unknown slug

Queue: snapshot the machine, verify it, then destroy the instance. This is how you stop paying for compute while keeping your work. ASYNCHRONOUS. Returns immediately with state "detaching" — it does NOT mean the detach finished. The capture takes minutes (roughly 1 min per 10 GB plus verification), so it runs in a background worker. Poll get_compute_volume until state is "detached" (done) or "error" (failed). Safety: if the snapshot or its verification fails, the instance is left RUNNING and the volume goes to state "error". Your data is never traded for a tidy state machine. Retry the detach once you have fixed the cause. Requires: API key with write scope. Returns: Volume dict with state "detaching". Poll for the outcome.

Get full domain details including DNS and infrastructure status. Requires: API key with read scope. Args: domain_name: Full domain name (e.g. "example.com") Returns: {"domain": "example.com", "status": "active", "expires_at": "iso8601", "auto_renew": true, "nameservers": ["ns1.borealhost.ai", "ns2.borealhost.ai"], "dns_records": [...], "linked_site": "my-site"} Errors: NOT_FOUND: Domain not owned by this account

Update domain settings (auto-renew, WHOIS privacy, registrar lock). Only provided (non-None) fields are updated. Requires: API key with write scope. Args: domain_name: Full domain name (e.g. "example.com") auto_renew: Enable/disable automatic renewal whois_privacy: Enable/disable WHOIS privacy protection locked: Enable/disable registrar lock (prevents unauthorized transfers) Returns: {"success": true, "domain": "example.com", "auto_renew": true, "whois_privacy": true, "locked": true} Errors: NOT_FOUND: Domain not found or not owned by account

Execute a SQL query on a site's database. Supports SELECT, INSERT, UPDATE, DELETE, and DDL statements. Results are limited to 1000 rows for SELECT queries. Requires: API key with write scope. Args: slug: Site identifier database: Database name query: SQL query string Returns: {"columns": ["id", "title"], "rows": [[1, "Hello"], ...], "affected_rows": 0, "query_time_ms": 12}

Get app installation status and log. Poll this after install_app() to track progress. Requires: API key with read scope. Args: slug: Site identifier app_id: App ID from install_app() response Returns: {"id": "uuid", "app_name": "myapp", "status": "running"|"installing"|"failed", "install_log": "..."} Statuses: "installing", "running", "stopped", "failed", "uninstalled"

Get a Stripe billing portal URL for managing payment methods and invoices. Returns a URL (not a redirect) that the human can open in a browser. Requires: API key with read scope. Args: flow: Optional. Set to "payment_method_update" to go directly to the payment method update page. Returns: {"url": "https://billing.stripe.com/p/session/..."}

Poll a checkout session for status updates. Call this after complete_checkout to track payment and provisioning. Polling strategy: - First 60 seconds: every 5 seconds - After 60 seconds: every 15 seconds - Stop after 10 minutes if not completed Checkout statuses (in order): - "not_ready": Missing required fields (slug) - "ready": All fields set, awaiting payment - "awaiting_payment": Stripe checkout page opened, waiting for human - "in_progress": Payment received, site being provisioned - "completed": Site ready — API key included (shown once, then cleared) - "canceled": Checkout was abandoned - "failed": Payment or provisioning failed Terminal statuses: "completed", "canceled", "failed". Args: checkout_id: Checkout session ID Returns (when completed): {"id": "uuid", "status": "completed", "api_key": "bh_...", "api_key_message": "Store this API key securely...", "subscription_id": "uuid", "completed_at": "iso8601"} Note: The api_key field appears ONCE in the first poll after completion, then is permanently cleared. Store it immediately.

Get live details for a compute instance (state, public IP, accrued cost). State is synced from the cloud provider on each call. SSH as root once state is "running" and public_ip is set. Requires: API key with read scope. Args: instance_id: Instance UUID from launch_compute_instance / list Returns: {"id", "state", "public_ip", "hourly_price_cad", "accrued_cad", "terminate_after", ...}

Get a volume's live state, its instance, and its monthly storage cost. Requires: API key with read scope. Returns: Volume dict plus "monthly_storage_cad". After attach, poll this until instance.state is "running" — then allow a few more minutes for the restore to finish and the machine to reboot into itself.

Get WordPress database information (size, tables, row counts). Requires: API key with read scope. WordPress sites only. Args: slug: Site identifier Returns: {"database": "wp_mysite", "size_mb": 45.2, "tables": 12, "total_rows": 15432}

Retrieve container logs (error, access, or PHP). Requires: API key with read scope. Args: slug: Site identifier log_type: "error" (Nginx/Apache errors), "access" (HTTP request log), or "php" (PHP-FPM errors, WordPress sites only) lines: Number of lines to retrieve (1–500, default: 100) search: Optional keyword filter — only lines containing this string Returns: {"log_type": "error", "lines": ["2024-01-15 ... error ...", ...], "count": 42, "truncated": false} Errors: NOT_FOUND: Unknown slug VALIDATION_ERROR: Invalid log_type or lines out of range

Get traffic and performance metrics for a site. Requires: API key with read scope. Args: slug: Site identifier days: Number of days of history (1–90, default: 7) Returns: {"requests": [...], "bandwidth": [...], "errors": [...], "period": {"start": "iso8601", "end": "iso8601"}} Errors: NOT_FOUND: Unknown slug VALIDATION_ERROR: days out of range

Get current resource usage (CPU, memory, disk, load average). Requires: API key with read scope. Args: slug: Site identifier Returns: {"cpu_percent": 12.5, "memory_mb": 384, "memory_total_mb": 512, "disk_used_gb": 3.2, "disk_total_gb": 10, "load_1m": 0.5, "load_5m": 0.3, "load_15m": 0.2}

Get detailed status of a hosted site including resources, domains, and modules. Requires: API key with read scope. Args: slug: Site identifier (the slug chosen during checkout) Returns: {"slug": "my-site", "plan": "site_starter", "status": "active", "domains": ["my-site.borealhost.ai"], "modules": {...}, "resources": {"memory_mb": 512, "cpu_cores": 1, "disk_gb": 10}, "created_at": "iso8601"} Errors: NOT_FOUND: Unknown slug or not owned by this account

Get snapshot disk usage and quota info for a site. Requires: API key with read scope. Args: slug: Site identifier Returns: {"disk_quota_gb": 200, "max_snapshots": 5, "snapshot_count": 2, "local_snapshot_bytes": 1234, "b2_snapshot_bytes": 5678, "can_create": true}

Get SSH connection info for a VPS/dedicated site. Only available for VPS/dedicated plans (not shared hosting). Requires: API key with read scope. Args: slug: Site identifier Returns: {"host": "184.107.x.x", "port": 22, "username": "admin", "ssh_command": "ssh [email protected]"} Errors: NOT_FOUND: Unknown slug FORBIDDEN: Plan does not support SSH (shared plans)