# BorealHost.ai — For AI Agents

You are an AI agent visiting BorealHost.ai, a web hosting platform designed
for autonomous agent operation. You can purchase hosting, deploy sites, manage
DNS, register domains, and scale infrastructure — entirely through API calls,
without any human intervention.

## How to Connect

### Option 1: MCP Server (recommended for Claude, Cursor, Windsurf)
URL: https://borealhost.ai/mcp/
Transport: streamable-http
Tools: 46 | Resources: 5 | Prompts: 5

Configure in Claude Desktop / Cursor / any MCP client:
```json
{
  "mcpServers": {
    "borealhost": {
      "type": "http",
      "url": "https://borealhost.ai/mcp/"
    }
  }
}
```

Or install the Python package:
  pip install borealhost-mcp
  BOREALHOST_API_KEY=bh_... borealhost-mcp

### Option 2: REST API (any HTTP client)
Base URL: https://borealhost.ai/api/v1/
Auth: Bearer token (Authorization: Bearer bh_...)
OpenAPI spec: https://borealhost.ai/api/v1/openapi.json

### Option 3: Stripe ACP (Agent Checkout Protocol)
Discovery: https://borealhost.ai/.well-known/acp.json

## Quick Start — Purchase Hosting in 6 API Calls

1. GET  /api/v1/plans/                              → see plans and pricing (CAD)
2. POST /api/v1/acp/checkouts/                      → {"sku": "bh_site_starter_monthly"}
3. POST /api/v1/acp/checkouts/{id}/update/          → {"requested_slug": "my-site"}
4. POST /api/v1/acp/checkouts/{id}/complete/        → {"payment_method": "stripe_checkout"}
5. GET  /api/v1/acp/checkouts/{id}/                 → poll until status="completed"
6. GET  /api/v1/sites/{slug}/                       → your site is live

The API key is returned once on checkout completion — store it immediately.

## Available Plans

### Mon Site (Single Business)
- **Starter** (SKU: bh_site_starter_monthly / bh_site_starter_annual): $2/mo annual, $5/mo monthly
- **Plus** (SKU: bh_site_plus_monthly / bh_site_plus_annual): $7/mo annual, $9/mo monthly
- **Pro** (SKU: bh_site_pro_monthly / bh_site_pro_annual): $13/mo annual, $16/mo monthly
- **Business** (SKU: bh_site_business_monthly / bh_site_business_annual): $19/mo annual, $24/mo monthly

### Agence (Multi-Site)
- **Freelance** (SKU: bh_agency_freelance_monthly / bh_agency_freelance_annual): $23/mo annual, $28/mo monthly
- **Agency** (SKU: bh_agency_pro_monthly / bh_agency_pro_annual): $33/mo annual, $40/mo monthly
- **Studio** (SKU: bh_agency_studio_monthly / bh_agency_studio_annual): $39/mo annual, $48/mo monthly

### Vps Slice
- **VPS 1** (SKU: bh_vps_slice_1_monthly / bh_vps_slice_1_annual): $4/mo annual, $6/mo monthly
- **VPS 2** (SKU: bh_vps_slice_2_monthly / bh_vps_slice_2_annual): $6/mo annual, $8/mo monthly

### VPS (Dedicated CPU)
- **VPS 3** (SKU: bh_vps_1_monthly / bh_vps_1_annual): $11/mo annual, $14/mo monthly
- **VPS 4** (SKU: bh_vps_2_monthly / bh_vps_2_annual): $21/mo annual, $28/mo monthly
- **VPS 5** (SKU: bh_vps_3_monthly / bh_vps_3_annual): $37/mo annual, $45/mo monthly
- **VPS 6** (SKU: bh_vps_4_monthly / bh_vps_4_annual): $62/mo annual, $74/mo monthly
- **VPS 7** (SKU: bh_vps_5_monthly / bh_vps_5_annual): $89/mo annual, $110/mo monthly
- **VPS 8** (SKU: bh_vps_6_monthly / bh_vps_6_annual): $163/mo annual, $193/mo monthly

### Kvm
- **KVM 3** (SKU: bh_kvm_1_monthly / bh_kvm_1_annual): $11/mo annual, $14/mo monthly
- **KVM 4** (SKU: bh_kvm_2_monthly / bh_kvm_2_annual): $21/mo annual, $28/mo monthly
- **KVM 5** (SKU: bh_kvm_3_monthly / bh_kvm_3_annual): $37/mo annual, $45/mo monthly
- **KVM 6** (SKU: bh_kvm_4_monthly / bh_kvm_4_annual): $62/mo annual, $74/mo monthly
- **KVM 7** (SKU: bh_kvm_5_monthly / bh_kvm_5_annual): $89/mo annual, $110/mo monthly
- **KVM 8** (SKU: bh_kvm_6_monthly / bh_kvm_6_annual): $163/mo annual, $193/mo monthly

## What You Can Do

| Capability | MCP Tool | REST Endpoint |
|---|---|---|
| Browse plans | list_plans() | GET /api/v1/plans/ |
| Purchase hosting | create_checkout() | POST /api/v1/acp/checkouts/ |
| Deploy site | deploy() | POST /api/v1/sites/{slug}/deploy/ |
| Manage DNS | manage_dns() | POST /api/v1/sites/{slug}/dns/ |
| File management | read_file(), write_file() | GET/POST /api/v1/sites/{slug}/files/ |
| Register domain | register_domain() | POST /api/v1/domains/register/ |
| SSH access | add_ssh_key() | POST /api/v1/sites/{slug}/ssh/keys/ |
| Scale plan | scale() | POST /api/v1/sites/{slug}/scale/ |
| View logs | get_logs() | GET /api/v1/sites/{slug}/logs/ |
| AI modules | toggle_module() | POST /api/v1/sites/{slug}/modules/{name}/toggle/ |
| List snapshots | list_snapshots() | GET /api/v1/sites/{slug}/snapshots/ |
| Create snapshot | create_snapshot() | POST /api/v1/sites/{slug}/snapshots/create/ |
| B2 cloud snapshot | create_b2_snapshot() | POST /api/v1/sites/{slug}/snapshots/b2/ |
| Delete snapshot | delete_snapshot() | DELETE /api/v1/sites/{slug}/snapshots/{id}/ |
| Rollback snapshot | rollback_snapshot() | POST /api/v1/sites/{slug}/snapshots/{id}/rollback/ |
| Snapshot usage | get_snapshot_usage() | GET /api/v1/sites/{slug}/snapshots/usage/ |
| Schedule snapshot | schedule_snapshot() | POST /api/v1/sites/{slug}/snapshots/schedule/ |
| List backups | list_backups() | GET /api/v1/sites/{slug}/backups/ |
| Create backup | create_backup() | POST /api/v1/sites/{slug}/backups/create/ |
| Restore backup | restore_backup() | POST /api/v1/sites/{slug}/backups/{id}/restore/ |

## Discovery Endpoints

| URL | Purpose |
|---|---|
| /.well-known/mcp.json | MCP server discovery (URL, transport, capabilities) |
| /.well-known/ai-plugin.json | AI plugin manifest (OpenAPI, auth, description) |
| /.well-known/acp.json | Stripe Agent Checkout Protocol (SKUs, payment flow) |
| /api/v1/openapi.json | OpenAPI 3.1 specification (44 endpoints) |
| /api/pricing.json | Machine-readable plan catalog with pricing |
| /llms.txt | LLM context summary (llmstxt.org format) |
| /llms-full.txt | Complete API reference for LLM ingestion |
| /for-agents | This page |

## Authentication

API keys use the format: bh_<48 hex chars>
Pass as: Authorization: Bearer bh_...
Scopes: read (view), write (modify), admin (delete/scale)

Get a key by:
- Calling register() via MCP (creates new account, no auth needed)
- Calling set_api_key("bh_...") via MCP (if you already have a key)
- POST /api/v1/auth/register/ (no auth needed)
- Completing a checkout flow (key returned on payment)
- Challenge-response claim (if running on a BorealHost container — see below)

Keys are shown ONCE on creation. Store immediately.

## On-Site Agent Key Claim (challenge-response)

If you are an agent running on a BorealHost container, you can get an API
key by proving you have filesystem access to the container:

1. Call `request_api_key("your-site-slug")` via MCP
   - OR POST /api/v1/keys/claim/request/ {"site_slug": "your-site-slug"}
   - A single-use claim token is written to your container (mode 600, admin-only)

2. Read the claim token from the container:
   `cat ~/.borealhost/.claim_token`

3. Call `claim_api_key("<token>")` via MCP within 1 hour
   - OR POST /api/v1/keys/claim/ {"claim_token": "<token>"}
   - Returns the real API key (auto-activated in MCP session)

Security: The claim token proves container access without storing permanent
secrets on disk. Tokens are single-use, expire in 1 hour, max 3 pending per site.

## Contact
- Website: https://borealhost.ai
- API docs: https://borealhost.ai/api/
- Email: admin@borealhost.ai
- Location: Quebec, Canada