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>)
Ret
Request an API key for a site YOU ARE RUNNING ON (challenge-response).
⚠ ONLY USE THIS IF YOU ARE EXECUTING INSIDE THAT SITE'S OWN CONTAINER. If
you bought or ordered the site from somewhere else, this is the wrong tool:
it returns "pending" and the pending never resolves, because the proof it
asks
Claim an API key using a claim token from the container.
After calling request_api_key(), read the claim token from the path that
call returned in `claim_path`, on that site's container, and pass it here.
The token is single-use — once claimed, it cannot be used again.
The API key is automatically
List available hosting plans with pricing and resources.
No authentication needed.
Args:
track: Filter by plan track. Valid values: "single_site", "agency".
⚠ The track is not the site count — most plans on BOTH tracks
include several sites (site_starter 5, site_plus 8, site_pr
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.
The response carries a `checkout_secret`, returned ONCE, that every later
step of this checkout requires. It is held in memory f
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,
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
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
List checkouts belonging to the authenticated account.
Requires: API key. Only checkouts with a recorded owner appear — every
checkout created while authenticated, plus every checkout that reached
payment. An anonymous checkout whose one-shot secret was lost cannot be
listed; create checkouts authe
Abandon an unpaid checkout and expire its Stripe payment link.
Use this to clean up abandoned attempts rather than leaving them to sit.
A completed checkout is never cancelled here — that would be a refund, and
it is refused.
Args:
checkout_id: Checkout session ID
Returns:
The checkout, w
Provision a site into a slot a plan you ALREADY PAY FOR includes.
Two different things can be meant by "create a site". Buying one is the
checkout flow (create_checkout → update → complete). This is the other: most
plans include several sites, and this uses one of them at no extra cost.
site_starte
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 st
The account's prepaid balance, and what THIS key may spend from it.
Two ceilings, and both apply: the balance bounds the ACCOUNT, the allowance
bounds this KEY within it. Plan against `spendable_cents`, which is the
lower of the two — a $50 balance behind a $5 allowance means $5, and
planning again
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
Create or delete DNS records for a site.
Requires: API key with write scope.
Args:
slug: Site identifier
action: "create" or "delete"
record_type: "A", "AAAA", "CNAME", "MX", "TXT", or "SRV"
subdomain: Subdomain part (e.g. "www", "mail"). Leave empty for
the apex/roo
Install an app template on a VPS/Cloud site.
Starts a background installation. Poll get_app_status() for progress.
Requires: API key with write scope. VPS or Cloud plan only.
Args:
slug: Site identifier
template: App template slug. Available: django, laravel, nextjs, nodejs,
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",
List installed apps on a site.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"apps": [{"id": "uuid", "app_name": "myapp", "template_slug": "django",
"status": "running", "domain": "myapp.mysite.borealhost.ai"}]}
List all snapshots and scheduled snapshots for a site.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"snapshots": [{"id": "uuid", "name": "snap-...", "status": "completed",
"storage_type": "local"|"b2", "size_bytes": 1234, "size_display": "1.2 Mo",
"cr
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
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
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
Rollback a site to a previous snapshot.
WARNING: This is destructive. The current state of the container will be
replaced with the snapshot contents.
Requires: API key with admin scope.
Args:
slug: Site identifier
snapshot_id: UUID of the snapshot to rollback to
Returns:
{"success":
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}
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_
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
List all backups for a site (automatic and manual).
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
[{"id": "uuid", "backup_type": "auto"|"manual", "status": "completed",
"size_bytes": 1234, "size_display": "1.2 Mo",
"timestamp": "iso8601", "notes": "..."
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 che
List one bounded page of immediate children in a backup directory.
This returns names and metadata only, never file contents. Use
``next_cursor`` from the response as ``cursor`` to request the next page.
Requires: API key with read scope.
Args:
slug: Site identifier
backup_id: UUID of a c
Start a selected-file recovery and return its durable ID immediately.
Existing destination paths are never replaced. The operation is
asynchronous; poll ``get_file_recovery`` with the returned ID.
Requires: API key with write scope.
Args:
slug: Site identifier
backup_id: UUID of a complet
Poll one selected-file recovery without waiting for it to finish.
Requires: API key with read scope.
Args:
slug: Site identifier
backup_id: UUID of the source backup
recovery_id: UUID returned by ``recover_backup_files``
Returns:
{"id": "uuid", "backup_id": "uuid",
"status":
Recover exactly one absent database from a completed backup.
The operation refuses an existing database and can never select ``all``.
It returns immediately; poll ``get_database_recovery`` with its durable ID.
Requires: API key with write scope.
Args:
slug: Site identifier
backup_id: UUID
Poll one database recovery without waiting for completion.
Requires: API key with read scope.
Args:
slug: Site identifier
backup_id: UUID of the source backup
recovery_id: UUID returned by ``recover_backup_database``
Restore a site from a backup.
WARNING: This is destructive. The current state of the site will be
replaced. Runs asynchronously — may take several minutes.
Requires: API key with admin scope.
Args:
slug: Site identifier
backup_id: UUID of the backup to restore from
Returns:
{"success
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"}}
E
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.
R
Delete a site and schedule resource cleanup (7-day grace period).
WARNING: This is destructive. The site will be inaccessible immediately.
After the grace period, its active service data is deleted. A final backup
remains recoverable for 30 days; immutable copies may remain until their
retention lo
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
Retur
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 an
List all subscriptions with plan details, pricing, status, and site slug.
Requires: API key with read scope.
Returns:
[{"id": "uuid", "plan_slug": "site_starter", "plan_name": "Starter",
"status": "active", "billing_period": "monthly",
"price": {"amount": 500, "currency": "cad"},
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.
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
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.
email_domains restricts the key to email tools on the named domains; use
email:read, email:write and optionally email:signon scopes. expires_at
List all API keys for the account.
Shows key metadata (name, prefix, scopes, last used) but never the
full key value.
Requires: API key with read scope.
Returns:
[{"id": "uuid", "name": "My Key", "prefix": "bh_a2...",
"scopes": ["read", "write"], "is_active": true,
"created_at": "
Revoke (deactivate) an API key. The key stops working immediately.
Requires: API key with write scope.
Args:
key_id: UUID of the key to revoke (from list_api_keys or whoami)
Returns:
{"success": true, "message": "API key revoked"}
Errors:
NOT_FOUND: Key not found or already revoked
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]"}
Er
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:
List files and directories in a site's container.
Path scoping depends on the plan:
- Shared plans: rooted at wp-content/ (WordPress content directory)
- VPS/dedicated plans: full filesystem access
Requires: API key with read scope.
Args:
slug: Site identifier
path: Relative path to list
Read the contents of a file from a site's container.
Max file size: 512KB. Binary files are rejected — use the site's
file manager or SSH for binary files.
Requires: API key with read scope.
Args:
slug: Site identifier
path: Relative path to the file
Returns:
{"path": "wp-config.php"
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": "...",
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_b
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": "...",
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"}
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": [...]}
Connect any MCP-compatible AI agent to BorealHost.ai — purchase hosting, deploy sites, manage DNS, register domains, and scale infrastructure, entirely through tool calls.
Quick Start
Remote Server (Recommended)
No installation needed. Connect directly to the hosted server: