# RareCloud

> RareCloud is an AI-first European cloud provider. We run our own OpenStack
> platform in the EU (Bucharest, Romania) and offer a Cloud VM billed by the
> hour with an automatic monthly cap, managed Kubernetes, block storage, load
> balancers and reserved IPs, all paid from a credit balance. Alongside the
> cloud we run classic, fixed-term hosting: KVM and Windows VPS, dedicated
> servers across 12 datacenters, and cPanel web hosting, plus residential and
> mobile proxies and domain registration. Everything is driven by a public
> REST API (https://api.rarecloud.io/v1) with scoped bearer tokens, and we
> ship an MCP server, a CLI and a Terraform provider so developers and AI
> agents can manage infrastructure programmatically. EU data, EU jurisdiction,
> real EU VAT invoices. Pay by card, PayPal, crypto or bank transfer.

## Cloud (own OpenStack, billed hourly from a credit balance)
- [Cloud VM](https://rarecloud.io/cloud-vm/): Cloud servers in the EU, deploy in about 30 seconds, billed by the hour with an automatic monthly cap, from EUR 3.99/month, in EUR or USD.
- [Managed Kubernetes](https://rarecloud.io/kubernetes/): Upstream Kubernetes managed by Gardener. You pay only for worker nodes at Cloud VM prices; optional high-availability control plane add-on at EUR 30/month.
- [Block Storage](https://rarecloud.io/block-storage/): Attachable block volumes for cloud servers at EUR 0.05 per GB per month, billed hourly, managed from the console or API.
- [Load Balancers](https://rarecloud.io/load-balancer/): Managed L4 load balancers with health checks and a public IP included, from EUR 7.30/month, billed hourly.

## Classic hosting (fixed-term, prepaid plans)
- [KVM VPS](https://rarecloud.io/kvm-vps/): Linux KVM virtual servers with NVMe storage, full root access and instant activation.
- [Windows VPS](https://rarecloud.io/windows-vps/): Windows RDP servers with full admin access, fast NVMe storage and 1 Gbps connectivity.
- [Dedicated Servers](https://rarecloud.io/dedicated-servers/): Bare-metal Intel Xeon servers with full root access across 12 datacenters.
- [Web Hosting](https://rarecloud.io/web-hosting/): cPanel web hosting with NVMe, free SSL and automated backups.
- [N8N VPS](https://rarecloud.io/n8n-vps/): Pre-installed n8n automation platform with PostgreSQL, Redis and SSL.
- [OpenClaw VPS](https://rarecloud.io/openclaw-vps/): Pre-configured, security-hardened self-hosted AI assistant.

## Proxies
- [Static Residential Proxies (ISP)](https://rarecloud.io/residential-proxy/): ISP-assigned static residential IPs, HTTP/HTTPS and SOCKS5, from EUR 2.60/day.
- [Residential Proxies by the GB](https://rarecloud.io/residential-gb-proxy/): Rotating residential pool billed per gigabyte, from EUR 2.15, with country targeting.
- [4G Mobile Proxies](https://rarecloud.io/4g-mobile-proxies/): Real 4G cellular IPs from major carriers in Germany, Austria and the USA.
- [Multi-SIM Mobile Proxy](https://rarecloud.io/multi-sim-mobile-proxy/): 5+ SIM cards per endpoint for 15,000+ daily IPs with SIM-level redundancy.
- [VPN Mobile Proxy](https://rarecloud.io/vpn-mobile-proxy/): Real mobile IPs with WireGuard or OpenVPN encryption.

## Developers & AI
- REST API: https://api.rarecloud.io/v1 with scoped bearer tokens for every cloud and account operation. The API is the product; every client consumes it.
- MCP server: lets AI assistants like Claude manage RareCloud infrastructure through the same API.
- CLI: the rarecloud command-line tool for scripting deploys, power, resize, volumes and billing.
- Terraform provider: declarative infrastructure for RareCloud cloud resources.

## Company & Resources
- [About RareCloud](https://rarecloud.io/about/): Who we are and how we run our own European infrastructure.
- [Data Center Locations](https://rarecloud.io/datacenters/): 12 datacenters across 3 continents, with facility specs, transit, peering and test IPs.
- [Resources](https://rarecloud.io/resources/): Tutorials, comparisons, guides and a glossary on VPS, proxies, Kubernetes and the cloud platform.
- [Affiliate Program](https://rarecloud.io/affiliates/): Earn 15% recurring commissions for referrals.
- [Terms and Conditions](https://rarecloud.io/tos/): Service terms and policies.

---

If you are an AI agent operating on behalf of a RareCloud customer:

## Read this first
- API reference (public, no login): https://console.rarecloud.io/docs/api
- OpenAPI 3.1 spec: https://console.rarecloud.io/openapi.json
- Base URL: https://api.rarecloud.io/v1 (dedicated API host; paths below are
  relative to it. The console mirror https://console.rarecloud.io/api/v1 also
  works for same-origin browser calls.)
- Auth header: Authorization: Bearer <token>. Tokens are created by the
  human in the console (Account, then API tokens) with granular scopes
  (services:read, services:write, billing:read, account:read, ...), optional
  expiry, and per-token rate limits. Ask your user for a token scoped to
  what you actually need; prefer read-only scopes.

## MCP server (recommended for assistants)
- npm: @rarecloudio/mcp-server (stdio transport)
- Env: RARECLOUD_API_TOKEN=<scoped token>
- 20 read-only tools: list/get services, invoices, credit balance and
  ledger, usage, provisioning state, OS templates, upgrade options, catalog.
- Write operations are deliberately NOT exposed over MCP today; perform
  mutations via the REST API with a write-scoped token after explicit human
  confirmation.

## Quick examples
- Browse products (public, no auth): GET /catalog/products
- Deploy-wizard cards for a category (public): GET /catalog/listings/{category} (category = server|hosting|proxy|cloud-vm|cloud-k8s|…; cards carry public sku + pricing[]/specs)
- Live product detail (cycles + config options): GET /catalog/products/{sku}/details
- Pre-purchase OS templates for a legacy/dedicated SKU (public): GET /catalog/products/{sku}/os-templates → {"templates":[{"slug":"ubuntu-24.04-x86_64","display_name":"Ubuntu","version":"24.04 LTS"}]}
- List regions (public): GET /catalog/regions (filter with ?backend=openstack|gardener|proxy)
- List OS images + marketplace apps (public): GET /catalog/images (apps have os_family="app" with summary/logo_slug)
- Managed-K8s versions on offer (public): GET /catalog/kubernetes-versions → {"versions":["1.32.0",...]}
- List services: GET /services/
- Suspended services: Service.suspendedBy is "billing" (top up to resume) or
  "admin" (abuse/legal — Service.suspendedReason says why; contact support).
- Deploy a cloud server: POST /services/ with JSON
  {"category":"cloud-vm","productId":"g-2vcpu-8gb","region":"bucharest-ro",
   "imageId":"ubuntu-24.04","hostname":"web-01","sshPublicKey":"ssh-ed25519 ..."}
  Response data: {serviceId, status, publicIp?, consolePassword?}. consolePassword
  is an auto-generated CONSOLE-ONLY (VNC) root password returned ONCE when you
  deploy with an SSH key (or no auth) and do NOT pass rootPassword — save it, it
  is shown only once, works only on the web/VNC console, and NOT over SSH. If you
  pass rootPassword WITHOUT an SSH key, no consolePassword is returned and your
  password works on both the console AND over SSH (root password login is enabled
  on the VM). If you pass rootPassword together with an SSH key, SSH stays
  key-only and your password works on the console only.
- Deploy a legacy product (server/hosting/proxy): POST /services/ with
  {"category":"server","productId":"...","billingCycle":"monthly","hostname":"box-01",
   "imageId":"ubuntu-24.04","rootPassword":"...","configOptions":{"<id>":"<optionId|qty>"},
   "customFields":{"<id>":"<value>"}}
  (configOptions + customFields are forwarded verbatim to the WHMCS order). A legacy
  VPS (category "server") REQUIRES a hostname and an auth credential (rootPassword OR
  an SSH key), and — when the product exposes an Operating System field — an OS via
  imageId (mapped to the product's OS field) or customFields; otherwise the order is
  rejected with INVALID_PARAM ("A hostname is required" / "An SSH key or a root
  password is required" / "Choose an operating system.").
- List your orders: GET /orders (purchase records; create via POST /services)
- Get one order: GET /orders/{id} (your own only; cross-user → 404)
- Check domain availability: GET /domains/availability?domain=example.com
  (scope domains:read → {domain, available, premium?})
- TLD pricing: GET /domains/tld-pricing (register/transfer/renew per TLD)
- List your domains: GET /domains (your own only)
- Get one domain: GET /domains/{id} (your own only; cross-user → 404)
- Register a domain: POST /domains with
  {"domain":"example.com","years":1,"nameservers":["ns1...","ns2..."]}
  (order-driven → {orderId, invoiceId, status:"Pending"}; registrar fulfils on pay)
- Transfer a domain in: POST /domains/transfers with
  {"domain":"example.com","epp":"<auth-code>","years":1}
- Renew a domain: POST /domains/{id}/renew with {"years":1,"autoRenew":true}
- Renew a legacy service (VPS/hosting/legacy proxy): POST /services/{id}/renew
  (returns {invoiceId, created}: the existing Unpaid renewal invoice, or a new
  one created inside the early-renew window; pay it from balance via
  POST /billing/invoices/{id}/pay or by card via the checkout URL. ACE proxies
  renew via POST /proxies/{id}/renew instead)
- Auto-renew from balance, per service: GET/PUT /services/{id}/autorenew
  {"enabled":false} to OPT OUT. Default (no setting) = AUTO: at the due date
  every renewal invoice is paid automatically from bonus first, then credit;
  cancel before the due date to let a service lapse. ACE proxies excluded.
  (order-driven → {orderId, invoiceId, status:"Pending"}; charged, registrar fulfils on pay)
- Nameservers: GET /domains/{id}/nameservers; PUT with {"nameservers":["ns1...","ns2..."]} (2–5)
- Registrant contact: GET /domains/{id}/contacts; PUT with the DomainContact fields
- DNS host records: GET /domains/{id}/dns; PUT with {"records":[{"hostname":"www","type":"CNAME","address":"example.com."}]}
  (registrar-dependent → 501 NOT_IMPLEMENTED when unsupported)
- Domain manage snapshot/actions: GET /domains/{id}/manage (combined state:
  status/expiry/autoRenew/idProtection/nameservers/locked; per-registrar
  nameservers+locked may be null); POST with {"action":"nameservers|lock|autorenew|idprotect|epp", ...}
- Managed-K8s kubeconfig: GET /services/{id}/kubeconfig (short-lived admin
  kubeconfig; your own cluster only → {kubeconfig, expiresAt})
- Cluster scale (read): GET /services/{id}/scale (worker pools + add-ons)
- Cluster scale (set): POST /services/{id}/scale with {"minimum":2,"maximum":5}
  (first worker pool; integers, min>=1 and max>=min; your own cluster only)
- Enable HA control plane: POST /services/{id}/high-availability (no body;
  add-only, idempotent — once enabled cannot be removed; adds €30/mo billed
  hourly; your own cluster only → 404 otherwise)
- Node pools (managed-K8s): create with up to 5 named pools via POST /services
  {"category":"cloud-k8s","productId":...,"pools":[{"name":"workers","minimum":1,"maximum":3},...]};
  manage later — GET /services/{id}/pools (list), POST /services/{id}/pools (add
  {name,machineType?,minimum,maximum,volumeSizeGb?}), PATCH /services/{id}/pools/{pool}
  (edit min/max/machineType/volume), POST /services/{id}/pools/{pool}/rename {"name":...}
  (rolling node replacement), DELETE /services/{id}/pools/{pool} (never the last;
  machineType resolved server-side; your own cluster only → 404 otherwise)
- Resize a cloud VM: POST /services/{id}/resize with {"flavor":"c-4vcpu-8gb"}
  (target plan PUBLIC SKU, not a raw flavor id — mapped server-side; async →
  202 {status:"resizing"}, then poll GET /services/{id} until ACTIVE; no disk
  shrink; billing follows the new plan; your own VM only → 404 otherwise)
- Reinstall a cloud VM (destructive rebuild, keeps the IP):
  POST /services/{id}/actions/reinstall  { "imageId": "ubuntu-24.04", "sshPublicKey": "ssh-ed25519 ..." }
  imageId is required (a curated slug from GET /services/{id}/os-templates). Provide password OR sshPublicKey,
  or neither for an auto-generated console (VNC) password returned ONCE as data.consolePassword.
  Async: poll GET /services/{id} until status=active. Your own VM only (else 404).
  Password/key semantics match deploy: a password without a key enables SSH password login; with a key, SSH stays key-only.
- Reset the root password on a RUNNING cloud VM (non-destructive, no reboot, data intact):
  POST /services/{id}/actions/reset-password  { "password": "8-128 chars" }
  Applied live via Nova os-set-password + qemu-guest-agent; returns data.status="reset-requested" (Nova
  accepted it; the guest applies it within ~1 min). Only available when GET /services/{id} reports
  capabilities.resetRootPassword=true (the VM booted with the guest-agent channel; older VMs must Reinstall
  first). The VM must be running (409 otherwise). Your own VM only (else 404).
  The new password always works on the VNC console; over SSH only on VMs deployed/reinstalled with password authentication (SSH-key VMs stay key-only).
- Cloud-VM resource-usage graphs (live CPU/memory/disk/network): GET /services/{id}/metrics?range=1h|24h|7d
  Returns data = { range, step, series{cpu_pct, mem_used_pct, mem_total_bytes, disk_read_bps, disk_write_bps,
  net_rx_bps, net_tx_bps}, latest, unavailable }; each series is an array of [unixSeconds, value|null].
  Scope services:read; your own VM only (else 404). unavailable=true (empty series) if the metrics store is
  briefly unreachable. Legacy VPS (numeric id) return a point-in-time snapshot instead (cpu_util_pct, ram_used_mb, …).
- Per-VPS SSH-key library (legacy Virtualizor) — list: GET /services/{id}/ssh-keys/library
  (each key has id, name, publicKey, fingerprint computed server-side; your own
  service only → 404 otherwise; distinct from the gateway GET /services/{id}/ssh-keys)
- Add a key to the library: POST /services/{id}/ssh-keys/library with {"name":"laptop","key":"ssh-ed25519 AAAA..."}
- Apply a selected SET of library keys to the VPS: POST /services/{id}/ssh-keys/library/apply with {"keyIds":["7","9"]}
- List block volumes: GET /volumes/
- Create a 50 GB volume: POST /volumes/ with {"sizeGb":50,"name":"data"}
- Attach a volume to a VM: POST /volumes/{id}/attach with {"serverId":"<nova-uuid>"}
- List load balancers: GET /load-balancers/
- Create an L4 LB: POST /load-balancers/ with
  {"name":"web-lb","port":80,"memberServerIds":["<nova-uuid>"]}
- List LB members: GET /load-balancers/{id}/members/
- List VPCs: GET /networks/
- Create a VPC: POST /networks/ with {"name":"staging"}
- Move a VM into a VPC: POST /networks/{id}/vms with {"serverId":"<nova-uuid>"}
- List firewalls: GET /firewalls/ (each: id, name, isDefault, inboundCount,
  outboundCount, attachedServerIds; one "default" firewall is the per-account
  baseline applied to every VM — editable, not deletable)
- Create a firewall: POST /firewalls/ with {"name":"web-fw"} (seeded with the
  default inbound rules: icmp + tcp 22/80/443; outbound open by default)
- Get one (rules + attachments): GET /firewalls/{id} → {inbound[], outbound[], attachedServerIds}
- Add a rule: POST /firewalls/{id}/rules with
  {"direction":"inbound","protocol":"tcp","portRangeMin":2310,"portRangeMax":2310,"remoteCidr":"0.0.0.0/0"}
  (direction inbound|outbound; protocol tcp|udp|icmp|all; ports omitted for icmp/all)
- Remove a rule: DELETE /firewalls/{id}/rules/{ruleId}
- Attach a firewall to a VM: POST /firewalls/{id}/attach with {"serverId":"<nova-uuid>"}
- Detach: POST /firewalls/{id}/detach with {"serverId":"<nova-uuid>"}
- Delete a firewall: DELETE /firewalls/{id} (the default firewall, or one still
  attached to a VM, can't be deleted → CONFLICT)
- Credit balance: GET /billing/credit/
- Account profile: GET /account (includes optional taxRatePercent: the VAT %
  applied to this client's invoices, 0 = tax-exempt/reverse-charge; prices are
  NET, so total = price * (1 + taxRatePercent/100). Absent = rate unknown.)
- Update account profile: PATCH /account with only the fields to change
  (firstName, lastName, companyName, address, city, postcode, country, phone,
  taxId, language, email). `email` updates the billing/contact email; the
  login email stays the same (contact support to change it).
- Payment options: GET /billing/payment-methods (WHMCS gateways; no stored-card vault)
- Active credit campaign (banner): GET /billing/campaign (or {campaign:null})
- Hosted pay link for an invoice: POST /billing/invoices/{id}/checkout-url
  (returns a logged-in URL; only works for your own invoice)
- Pay-from-balance preview: GET /billing/invoices/{id}/pay-preview (read-only:
  how much promo bonus + real credit a pay-from-balance would use, and any
  shortfall; consumes nothing). Pay it: POST /billing/invoices/{id}/pay
  {"payWith":"credit"} — bonus is always consumed before real credit.
- Two-factor status: GET /account/two-factor (your own account only)
- Manage two-factor: POST /account/two-factor with
  {"action":"setup"} | {"action":"enable","code":"123456"} | {"action":"disable","code":"123456"}
- List account SSH keys: GET /account/ssh-keys (your own keys; each has id, name,
  fingerprint, publicKey, createdAt)
- Register an SSH key: POST /account/ssh-keys with {"name":"laptop","publicKey":"ssh-ed25519 AAAA..."}
  (returns {id,name,fingerprint}; name must be unique; an invalid key → INVALID_PARAM)
- Delete an SSH key: DELETE /account/ssh-keys/{id} (owner-only; not yours → NOT_FOUND)
- Resend email verification: POST /account/verify-email/resend (your own account only;
  no body — returns {sent:true} or {sent:false,reason:"already_verified"})
- Affiliate status + stats: GET /account/affiliate (your own account only) —
  {active:false} until activated; then the full native affiliate page:
  {active:true, id, referralLink, visitors (clicks), signups, conversionRate,
  balanceCents (available), pendingCents (pending maturation), withdrawnCents,
  payoutMinimumCents, currency, referrals:[{date, service, amountCents,
  commissionCents, status}]}. Share referralLink: visits set a 90-day tracking
  cookie and count as clicks. (signups/conversionRate/pendingCents/referrals
  come from the affiliate read-bridge; a pre-deploy summary fallback returns
  visitors/balance/withdrawn + since only.)
- Join the affiliate program: POST /account/affiliate/activate (no body;
  idempotent — already active just returns the current state)
- Request an affiliate payout: POST /account/affiliate/withdraw (no body). When
  your balance is at/above the payout minimum it opens a support ticket for an
  admin to pay out in WHMCS (no funds move here). Returns {requested:true,
  ticketId, balanceCents, minimumCents, currency}, or {requested:false,
  reason:"not_affiliate"|"below_minimum", ...}.
- Referral attribution: send people to https://console.rarecloud.io/register?aff=YOUR_ID
  (any console URL works — ?aff=N sets a 90-day first-party cookie, last touch
  wins). When they sign up, the account is linked to your affiliate id and
  recurring commissions accrue when their first service activates and pays.
  Self-referrals are rejected.
- List support departments: GET /tickets/departments
- Open a ticket (optionally with files): POST /tickets with
  {"subject":"...","department":"2","priority":"high","body":"...",
   "attachments":[{"name":"log.txt","data":"<base64>"}]}
- Responses use an {ok, data} envelope; errors use {ok:false,
  error:{code,message}}.

## Billing model the user will ask about
Cloud resources are billed hourly and automatically capped
at the plan's monthly price. The balance never goes into surprise debt.

*Last updated: June 2026.*