# 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, > S3-compatible object storage, load balancers and reserved IPs, metered hourly > and invoiced monthly. Alongside the cloud we run classic, fixed-term hosting: > KVM and Windows VPS in 11 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, > invoices in EUR or USD from an EU company. Pay by card, PayPal, crypto or bank transfer. ## Cloud (own OpenStack, metered hourly, invoiced monthly) - [Cloud VM](https://rarecloud.io/cloud-vm/): Cloud servers in the EU, ready in less than a minute, 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, billed by the hour (not capped). - [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 stable public IPv4, EUR 9/month with the public IP included, billed hourly and capped at EUR 9 a month. - [AI Sandboxes](https://rarecloud.io/ai-sandboxes/): Disposable, isolated environments for AI agents to run code and commands, billed by the second. In beta. - [Container Registry](https://rarecloud.io/container-registry/): Private Docker/OCI registry with free and paid tiers, push and pull credentials and Kubernetes cluster linking. - [Object Storage](https://rarecloud.io/object-storage/): S3-compatible buckets in 16 regions, chosen per bucket, EUR 10/month including 1 TB and egress up to your stored volume, then EUR 0.01/GB-month, billed hourly. Works with aws-cli, rclone, s3cmd, mc and every S3 SDK. ## 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, in 11 locations. - [Windows VPS](https://rarecloud.io/windows-vps/): Windows RDP servers with full admin access, fast NVMe storage and 1 Gbps connectivity. - [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. - [ISP Proxies Global](https://rarecloud.io/isp-proxies-global/): Residential ISP proxies in 120 countries, 1,800+ cities and 900+ ASNs. Pick the city and ISP for every IP, HTTP and SOCKS5 on one port, unlimited bandwidth, from EUR 4.90/month. - [Residential Proxies by the GB](https://rarecloud.io/residential-gb-proxy/): Rotating residential pool billed per gigabyte or monthly fixed bucket (pay-as-you-go or monthly plans available), from EUR 2.15, with country targeting. - [4G Mobile Proxies](https://rarecloud.io/4g-mobile-proxies/): A private line on a real 4G carrier connection in Germany or the USA, with the IP rotation managed for you. - [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. - Residential Proxies Global: rotating residential IPs billed by the GB with monthly packages from 1 to 1000 GB, three tiers (no targeting, country, or country/region/city/ISP), HTTP and SOCKS5 on one port, from EUR 1.10/month. - ISP Proxies Global: static ISP IPs in many countries, placed per location (country, region, city, ISP network); HTTP and SOCKS5 on isp.rarecloud.io:443, monthly plans of 1 to 200 IPs from EUR 4.90/month. ## 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 (0.6.0): the rarecloud command-line tool for scripting deploys, power, resize, volumes, load balancers, Object Storage, the container registry, AI Sandboxes, outbound email status and requests, and billing. - Terraform provider (0.6.0): declarative infrastructure for RareCloud cloud resources, Object Storage buckets and keys, container registry credentials and cluster links, AI Sandboxes and the outbound email status of a cloud VM. - AI code sandboxes: isolated, ephemeral execution environments for AI agents under `/sandboxes` (create from a template at a size, list templates and sizes with their hourly price, run code or shell commands, read/write files). Sizes `xs` and `s` are available today; larger sizes answer 409 size_unavailable until capacity is extended, and GET /sandboxes/sizes reports which sizes run. ## 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 (the cloud region in Bucharest, classic VPS in the other 11), 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. - [MCP server docs](https://rarecloud.io/resources/docs/mcp-server/): Install @rarecloudio/mcp-server in Claude Code, Claude Desktop, Cursor or Windsurf; token scopes, the confirm gate and all 224 tools by area. - [CLI docs](https://rarecloud.io/resources/docs/cli/): Install the rarecloud CLI on macOS, Linux or Windows, authenticate, and every command with its flags. - [Terraform provider docs](https://rarecloud.io/resources/docs/terraform/): Configure rarecloudio/rarecloud, every resource and data source with its arguments, and example configs. - [Cloud VM docs](https://rarecloud.io/resources/docs/cloud-vm/): Deploy, images, power, web console, reinstall, password reset, resize, snapshots and restore, tags, reverse DNS and outbound email, from the console, API, CLI and more. - [API getting started](https://rarecloud.io/resources/docs/api-getting-started/): Create a scoped token, make your first calls, read the response envelope and error codes, stay inside rate limits, and retry creates safely with an Idempotency-Key. - [Limits and quotas docs](https://rarecloud.io/resources/docs/limits-and-quotas/): Read your limits and usage, estimate whether a Kubernetes cluster fits, and ask for a higher limit. - [AI Sandboxes docs](https://rarecloud.io/resources/docs/ai-sandboxes/): Create an isolated sandbox, run Python, Node or shell commands, read and write files, with every CLI command and the Terraform resource. In beta. - [Container Registry docs](https://rarecloud.io/resources/docs/container-registry/): Enable the registry, create credentials, docker login, push and pull, link Kubernetes clusters, plus every CLI command and Terraform resource. - [Affiliate Program](https://rarecloud.io/affiliates/): Earn 15% recurring commissions for referrals. - [Partners](https://rarecloud.io/partners/): Preferential pricing for developers, agencies and resellers who bring many clients or large resource volumes. - [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 . 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. The session cookie comes from the console's own sign-in and is meant for the console only: an integration uses a token. - Safe retries: create requests (POST) accept an optional Idempotency-Key header. Send a fresh value (a UUIDv4) per operation and the SAME value when retrying the same request after a timeout: it runs at most once and the retry gets the original answer (header Idempotent-Replayed: true; one-time secrets are omitted and listed in secretsOmittedOnReplay). Keys are kept 24 hours. - 429 (rate limit) and 503 BACKEND_UNAVAILABLE carry Retry-After: wait that many seconds, and retry a create only with the same Idempotency-Key. - Read-only resources: the human can switch API access off for any resource in the console. Reads still work; changes and credential reads answer 403 RESOURCE_PROTECTED with a console link. Objects carry apiAccess (full|read_only) and GET /api-access lists the read-only ones. Do not retry or work around RESOURCE_PROTECTED: ask the human. Tokens can never flip the switch. ## MCP server (recommended for assistants) - npm: @rarecloudio/mcp-server (stdio transport) - Env: RARECLOUD_API_TOKEN= - Version 0.6.0: 224 tools, 111 read tools plus 113 write tools (servers, Kubernetes, volumes, networks, reserved IPs, firewalls, load balancers, Object Storage, container registry, AI Sandboxes, snapshots, quotas, reverse DNS, domains, proxies, account, billing alerts, tickets). 86 write tools are gated: those that spend, are destructive, are disruptive (power off, reboot, detach, roll nodes, replace DNS or credentials) or are sensitive (grant access, speak for the user) refuse to run, making no API call, unless called with confirm:true; surface the action and its cost or consequence to the human first. check_order asks whether deploy_service would be accepted without creating anything. The 46 tools that create or change through an idempotency-keyed route take an optional idempotency_key; reuse it to retry safely. There are no tools for your account password, 2FA, sub-user invites, API tokens, payment methods, top-ups, invoice payment, affiliate activation or withdrawal, or the per-resource API access switch. AI Sandboxes are available in beta. The Container Registry is live: its tools enable the registry, manage credentials, repositories and cluster links. If the registry is ever paused, its reads stay open (list_registry_tiers and suggest_registry_handle answer normally; get_registry and the other account reads answer 404 "not enabled" without an account) and every registry write tool gets a 503. - Claude Code: claude mcp add rarecloud -e RARECLOUD_API_TOKEN=rc_pat_... -- npx -y @rarecloudio/mcp-server ## 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 VPS 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 or ?line=cloud|legacy) - List OS images (public): GET /catalog/images (only images a deploy accepts right now are listed, in this order; the curated distro slugs are ubuntu-24.04, ubuntu-22.04, debian-12, rocky-9, almalinux-9 and centos-stream-9, each listed once its image is available) - Managed-K8s versions on offer (public): GET /catalog/kubernetes-versions → {"versions":["1.35.6"]} (newest first; the list changes over time; pass one as k8sVersion when you create a cluster, or omit it to get the newest) - List services: GET /services/ - Check an order before placing it: POST /services/preflight with the same body as POST /services (scope services:write). Runs the same balance check as a dry run: nothing is created, held or charged. Answers whether the order would be accepted and, when refused, why plus the add-funds or pay-invoice link for the human. - Suspended services: Service.suspendedBy is "billing" (pay the open invoice to resume; for a cloud resource that is the invoice on GET /billing/state) or "admin" (abuse/legal: Service.suspendedReason says why; contact support). An admin-suspended cloud VM cannot be started or operated, but its owner can still destroy it. Load balancers and volumes carry the same status and suspendedBy. Reserved IPs and snapshots carry suspendedBy alone, present only while suspended. While an invoice is unpaid a load balancer passes no traffic and takes no new members, and a reserved IP or a volume cannot be attached, and a snapshot cannot be restored or booted from: those calls answer CONFLICT. Deleting or releasing stays allowed. Unpaid, they are deleted on the same calendar as a VM. - 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. Startup configuration (cloud-vm only): add "userData", plain text, not base64, whose first line starts with #cloud-config or #!. cloud-init runs it at first boot. At most 32 KiB measured as UTF-8; a NUL byte, other formats (#include, MIME, #cloud-boothook) and any other product are refused with 400 INVALID_PARAM, and POST /services/preflight refuses the same. A payload near the limit can also be refused when it does not fit next to this VM's SSH key and password. The request body may be at most 128 KiB (413 PAYLOAD_TOO_LARGE above it). The contents are not checked: invalid YAML does not fail the request, and the VM is reported ready without waiting for your script. Keep our own first-boot steps enabled: turning them off breaks password reset, SSH key login and Reserved IP routing on that VM. Do not put secrets in it: any local process inside the VM can read it. It is not stored and no API returns it, so a reinstall does not reuse it. From a snapshot: the snapshot needs cloud-init and should be cleaned with `cloud-init clean` before it is taken, or nothing runs and the API reports no error. - Deploy a legacy product (server/hosting/proxy): POST /services/ with {"category":"server","productId":"...","billingCycle":"monthly","hostname":"box-01", "imageId":"ubuntu-24.04","rootPassword":"...","configOptions":{"":""}, "customFields":{"":""}} (configOptions + customFields are forwarded verbatim to the 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."). Config-option values are validated against the product's details; an option marked "disabled" there (a retired location, e.g. Bucharest for legacy VPS: it is moving to RareCloud Cloud) is refused with INVALID_PARAM carrying its disabledReason. Location of a legacy VPS: choose it. List the locations with GET /catalog/regions?line=legacy (CLI: rarecloud catalog regions); the plan's own locations, with the closed ones marked "disabled", are the location option in GET /catalog/products/{sku}/details. Then send that option in configOptions, or the "region" slug (e.g. "frankfurt-de") and the API selects that location. A closed location, or a region the plan does not offer, is refused with INVALID_PARAM (the message lists the open regions). With neither, the API picks one of the plan's open locations at random, so pass a region whenever the location matters to you. - 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":"","years":1} - Renew a domain: POST /domains/{id}/renew with {"years":1,"autoRenew":true} (order-driven → {orderId, invoiceId, status:"Pending"}; charged, registrar fulfils on pay) - 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. Services under /proxies renew via POST /proxies/{id}/renew instead) - Mobile proxy order prices: GET /proxies/mobile/prices → {currency, prices:[{kind, location, monthlyCents, oneDayCents}]}, what ordering a mobile proxy bills per line in your billing currency (a full plan = monthlyCents × months × quantity; a 1-Day test = oneDayCents; monthlyCents is null while that product cannot be priced) - Retired mobile products: a new order with "kind":"mobile-vpn" or "location":"at" (Austria) answers 400 INVALID_PARAM. Existing VPN lines still renew; Austria lines run to the end of their paid period. GET /proxies/mobile/prices may still list them. - Mobile 1-Day test + upgrade: order a mobile proxy with {"kind":"mobile-4g","term":"test24h"} (quantity forced to 1, no months) for a 1-Day full-proxy test; upgrade it in place to a full 1/3/6/12-month plan via POST /proxies/{id}/renew {"months":3} (keeps the same credentials; charged the full-plan price, the test payment is not credited) - Reactivate a lapsed proxy (MOBILE-ONLY): an expired/cancelled MOBILE service can still be renewed via POST /proxies/{id}/renew for 14 days after expiry (same line, new expiry counted from now). A lapsed ISP/GB residential service cannot be renewed: order a new one. The service object carries `reactivatable` (boolean) and `reactivationDaysLeft` (14…1, or null when not applicable: active/PAYG/1-Day test/non-mobile kind/past the window). Past the window or for non-mobile kinds, renew returns 409 REACTIVATION_WINDOW_CLOSED. - 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. Services under /proxies are excluded; see POST /proxies/{id}/auto-renew. - Download VPN config file (mobile-vpn proxy lines only): GET /proxies/{id}/vpn-config Returns the OpenVPN (.ovpn) or WireGuard (.conf) connect file as plain text; Content-Disposition header provides the filename for download. - Proxy service objects (GET /proxies, GET /proxies/{id}) include an optional `reference` string: an opaque order reference for support and cross-referencing a service. Null when no order id was recorded. Never the service code. - Proxy service objects also carry `port` (integer|null): the cached port for mobile lines, so a specific line can be identified without opening its proxy-list. Null when not yet cached (it backfills daily server-side). - Proxy service objects also carry `tags` (string[], [] when untagged): the customer's own labels. Each tag is 1-40 characters, no comma and no control or invisible characters; at most 10 per proxy; case-insensitive duplicates are dropped and a tag you already use keeps its existing spelling. - Set a proxy's tags (replaces the set, [] clears): PUT /proxies/{id}/tags {"tags":["Scraper","EU"]} → {tags:[...]} - List your proxy tags with counts: GET /proxies/tags → [{tag, count}] - Filter proxies by one tag: GET /proxies?tag= (case-insensitive) - Per-IP location (static residential/ISP only): entries in GET /proxies/{id}/proxy-list may carry an optional `location` string: where THAT IP exits, as "City (Network)" (either half alone when only one is known). A custom ISP pack spans several cities and carriers, so the service-level location is wrong for most of its IPs. It is learned by POST /proxies/{id}/check and stored, so it is already correct on the next read. Omitted when nothing is known for that IP, and never present for GB plans (rotating pool) or mobile. - GB plan bandwidth: GET /proxies/{id}/bandwidth carries `state`: "ok" (live reading) or "exhausted" (every GB on the plan is used up and its proxies have stopped; total = used = plan size, available 0). On an exhausted plan, GET/POST /proxies/{id}/proxy-requests return 409 CONFLICT with error.details[0].message == "bandwidth_exhausted". Renewing does not restore a used-up plan: POST /proxies/{id}/renew answers the same 409 CONFLICT before any invoice is created. Order a new GB plan to continue. PAYG plans (prepaid GB, no term) report "exhausted" too; for them, order more GB to continue. - Closed GB plans: proxy service objects (GET /proxies, GET /proxies/{id}) carry an optional `closedReason` (null | "bandwidth_exhausted" | "upstream_flagged"). It is set when a fixed-monthly GB plan was closed because its bandwidth is used up: status is then "expired", auto-renew is off and there is no refund. Such a plan cannot be renewed or reactivated: POST /proxies/{id}/renew and POST /proxies/{id}/cancel with {"cancel":false} both answer 409 CONFLICT with error.details[0].message == "bandwidth_exhausted". Order a new GB plan to continue. - Residential Proxies Global (kind "residential-global"): a rotating residential pool billed by traffic. Three tiers: "non-geo" (no targeting), "country" (pick a country), "full-geo" (country, region, city, ISP network). Monthly GB packages 1/2/5/10/50/100/250/500/1000; the GB reset every month (1 GB = 10^9 bytes). Prices per month in EUR (USD at the current rate), Non-Geo 1.10/2.10/4.95/9.45/44.25/84.25/193.00/ 356.00/668.50, Country 2.15/4.15/9.90/18.90/88.50/168.50/386.00/712.00/1337.00, Full Geo 2.80/5.40/12.90/ 24.60/115.00/219.00/502.00/926.00/1738.00. HTTP and SOCKS5 on the same host and port (proxy.rarecloud.io; read the port from the credentials), username + password auth only. Catalog: GET /proxies/residential-global/catalog → {tiers:[{id, label, targeting, packages:[{gb, eur, usd}]}], availability:{ordersEnabled, message}}. Order: POST /proxies {"kind":"residential-global","tier":"country","gb":10,"autoRenew":true,"tags":[]} → {service, invoiceId, paid}; the plan is usually active within seconds. When it is still being set up the service has status "provisioning" and turns "active" on its own: do not order again. While new orders are paused this answers 503 BACKEND_UNAVAILABLE and nothing is charged. The service object adds residentialGlobal {tier, packageGb, periodStart}. Login: GET /proxies/{id}/credentials → {host, port, username, password, protocols:["http","socks5"], endpoints:[{region:"auto"|"eu"|"us"|"asia"|"in"|"au", host}]}; host is the automatic entry point and endpoints lists it with one per region (eu.proxy.rarecloud.io, us., asia., in., au.). The username looks like customer-abc123. POST /proxies/{id}/credentials/rotate always answers 409 CONFLICT: the plan login has no password change. Targeting is in the username, lowercase, separated by dashes: country-, region-, city-, asn-, sid- (keeps one IP), ttl- (1 to 1800), strict-true. Non-Geo accepts sid and ttl; Country adds country; Full Geo adds region, city, asn and strict. Example: customer-abc123-country-de-sid-abc123. Lists for the flags: GET /proxies/residential-global/geo/countries (and regions, cities, asns for Full Geo)?tier=full-geo&country=de®ion=bavaria → [{code, name}], [{slug, name}] or [{asn, name}]. Traffic: GET /proxies/{id}/bandwidth → {unit:"GB", total, used, available, state:"ok"|"exhausted", reason?, grants:[{gb, source, createdAt}]}. When the GB are used up, or the plan expires, new connections are refused until you add GB or renew. Add GB: POST /proxies/{id}/top-up {"gb":10} (Idempotency-Key REQUIRED, 400 without it) → {invoiceId, bandwidth}; paid from account credit, valid until the end of the current plan period. Auto top-up: GET and PUT /proxies/{id}/auto-top-up {"enabled":true,"thresholdGb":2,"packageGb":10, "monthlyMax":3} (thresholdGb 1 to 1000, monthlyMax 1 to 10): when the traffic left drops under thresholdGb, packageGb is bought from credit, at most monthlyMax times per month. With too little credit nothing is invoiced and one email per month says so. Renewal: POST /proxies/{id}/renew (periods can only be 1) and POST /proxies/{id}/auto-renew; unused GB expire at renewal. - ISP Proxies Global (kind "isp-global"): static ISP IPs placed per location. Monthly plans of 1/4/6/10/15/25/50/100/200 IPs at EUR 4.90/14.90/19.90/27.90/41.90/63.90/124.90/209.90/349.90 per month (USD at the current rate). One username per IP, one password per plan. Every IP connects to isp.rarecloud.io:443 (HTTP and SOCKS5 on the same port), IPv4 only, username + password auth only (no IP whitelist). The IP address behind a username can change from time to time; the city and the ISP network stay fixed, so sites see the same network and location. Catalog: GET /proxies/isp-global/catalog → {tiers:[{ips, eur, usd}], planSizes, cycle:"month", maxChangesPerIp:5, endpoint:{host, port}, availability:{ordersEnabled, message}}. Countries: GET /proxies/isp-global/location-countries → {countries:[{code, name, count, regions:[{name, count, cities:[{name, count}]}]}]}. Locations: GET /proxies/isp-global/locations?country=DE®ion=Berlin&city=Berlin&q=3320&page=1 → {locations:[{locationId, country, region, city, isp, asn, available}], total, hasMore, page, perPage}. `region` is the state, `city` is the city, `q` is the ISP name or ASN. One page is 100 locations; page count is `total` divided by `perPage`, rounded up. Order: POST /proxies {"kind":"isp-global","ips":10,"placements":[{"locationId":123,"count":4}], "periods":1,"tags":["EU"]} (placements optional, at most `ips` in total; periods 1/3/6/12, 5/10/20% off for 3/6/12) → {service, invoiceId, paid, proxies, placementWarnings:[{locationId, requested, available}]}. A location that runs out of IPs does not fail the order: the plan is bought, those IPs stay unplaced and are listed in placementWarnings. While new orders are paused the order answers 503 BACKEND_UNAVAILABLE and nothing is charged. Place unplaced IPs later: POST /proxies/{id}/ips/place {"placements":[{"locationId":123,"count":2}]} → {placed, unplaced, warnings, ips}. Search locations for a plan: GET /proxies/{id}/locations (same query and answer as the catalog search). Both searches together allow 10 requests per minute per account (then 429 RATE_LIMITED). List the IPs: GET /proxies/{id}/ips → {ips:[{proxyId, username, country, region, city, isp, asn, changesLeft}]} (never the password). Each IP gets 5 location changes per billing period (placing an unplaced IP does not use one). Move one IP: POST /proxies/{id}/ips/{proxyId}/location {"locationId":456} → {ip, changesLeft}. Move many: POST /proxies/{id}/ips/location {"moves":[{"proxyId":1,"locationId":456}],"dryRun":true} → {moved, results:[{proxyId, ok, locationId?, username?, changesLeft?, error?, message?}], ips} (1 to 1000 moves, each IP once; dryRun checks without changing anything; a refused move has error "no_changes_left" | "out_of_stock" | "failed" and a message to show). All three POSTs accept Idempotency-Key. A moved IP gets a new username at once; the old username stops working (read it from the response or GET /proxies/{id}/ips). Traffic: GET /proxies/{id}/usage?days=30 (days 7, 30 or 90; default 30) → {days, start, end, bytes, uploadBytes, downloadBytes, requests}: totals of the whole plan for [start, end), where end is the next whole UTC hour. Updated every few minutes. Still readable after the plan ended while the history is kept (then 410 GONE). Other days values → 400 INVALID_PARAM. No changes left → 400 INVALID_PARAM; location out of IPs → 409 CONFLICT; IP not in the plan → 404. Credentials: GET /proxies/{id}/proxy-list returns one entry per placed IP where `ip` carries the hostname isp.rarecloud.io, port 443, the IP's username, the plan password and location "City, ISP (ASnumber)", for example "Berlin, Telekom (AS3320)". The service object adds endpoint, ips {total, placed, unplaced, changesPerIp}, locations [{country, region, city, isp, asn, count}], periodEndsAt, upstreamAutoRenew, flaggedAt and interruption (boolean: true while the plan is active and its network is being restored; only on this kind); closedReason can be "upstream_flagged" (plan stopped after a usage review, status "cancelled", cannot be resumed); authMethod is always "password". Not offered: IP replacements, rotation, format switch, auth method or IP whitelist changes, credential changes. Those routes answer 400 INVALID_PARAM "This action is not available for this product". Renewal: POST /proxies/{id}/renew {"periods":1|3|6|12} extends a plan the customer has paid for. POST /proxies/{id}/auto-renew is the same action as cancel and resume: enabled false tells the provider to stop renewing, enabled true turns it back on. A local-only flag is not stored on its own. There is no grace period after expiry: a lapsed plan cannot be renewed (409); order a new one. Cancel (POST /proxies/{id}/cancel) stops renewal at the end of the paid term (activeUntil); the plan keeps working until then and {"cancel":false} undoes it before that date. Cancel, resume, place and moves need an active plan (else 409 "This plan is not active."). Reads of a plan that has ended answer 410 GONE "This plan has ended and cannot be resumed. Order a new plan to continue." - Nameservers: GET /domains/{id}/nameservers; PUT with {"nameservers":["ns1...","ns2..."]} (2 to 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}) - Managed-K8s long-lived kubeconfigs: POST /services/{id}/kubeconfigs {name, role: admin|view, ttl: 30d|90d|1y|never} → credential + kubeconfig; GET /services/{id}/kubeconfigs (list); GET .../kubeconfigs/{credId}/download; DELETE .../kubeconfigs/{credId} (revoke: instant, deletes the ServiceAccount) - 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) - Reverse DNS for a cloud VM's primary IPv4: GET /services/{id}/rdns reads the current PTR; PUT /services/{id}/rdns with {"hostname":"mail.example.com"} replaces it; DELETE /services/{id}/rdns removes it. The API derives the IP from your owned VM and never accepts an arbitrary address. Only configured RareCloud reverse zones are writable; another account's VM returns 404. - Outbound email on a cloud VM: TCP port 25 is blocked on new servers (IPv4 and IPv6); ports 465 and 587, inbound port 25, every other TCP port, UDP, ICMP, GRE, ESP, AH, SCTP, VRRP and IP-in-IP stay open, and protocol 41 over IPv6. 6in4 tunnels (protocol 41 over IPv4) cannot be allowed by security groups; ask support on a ticket. Send through 465 or 587 (submission) or ask for the unblock. GET /services/{id}/smtp returns {status, request, canRequestAfter} with status open | blocked | pending | approved | rejected. POST /services/{id}/smtp/unblock-request opens the request with {"purpose":"own_domain_mail"|"transactional"|"newsletter"|"other","software":"Postfix", "domains":["mail.example.com"],"spf":true,"dkim":true,"dmarc":true, "recipients":"own_users"|"opted_in"|"other","messagesPerDay":100,"acceptPolicy":true} (purposeOther, recipientsOther, listSource and rdns are the optional or conditional extras; the schema is in openapi.json). Our team reviews it through a support ticket. One request can be pending per VM; after a rejection or a revoked approval a new one is accepted 7 days later (409 CONFLICT with details[0].field = "canRequestAfter" and the ISO date). A firewall rule or attach that would open port 25 on a restricted, unapproved VM answers 409 SMTP_EGRESS_NOT_APPROVED. VM create and moving a VM to another VPC answer 409 SMTP_EGRESS_NOT_APPROVED while the Private network firewall allows outbound TCP 25. New firewalls allow every outbound TCP port except 25, plus UDP, ICMP, GRE, ESP, AH, SCTP, VRRP and IP-in-IP, and protocol 41 over IPv6 (for every account); add an outbound rule for TCP 25 where a server may send email. 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, or the id of one of YOUR OWN snapshots (a snapshot of a different VM is allowed) - both come from GET /services/{id}/os-templates, whose entries carry kind: "stock" | "snapshot". A snapshot is refused if it needs a bigger disk than this VM has; the error names both sizes. 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). Refused with 409 and nothing changed while status=error (message starts "SERVER_IN_ERROR_STATE:"; re-imaging or destroying it now would erase its disk, so contact support first) or while the state is not settled (status=pending; message starts "SERVER_STATE_UNCONFIRMED:"; retry once it settles). Password/key semantics match deploy: a password without a key enables SSH password login; with a key, SSH stays key-only. Optional "userData": same rules as deploy. A reinstall does not reuse an earlier value: send it again, or the VM gets none. Refused with 400 INVALID_PARAM on a legacy VPS, and on a snapshot of this same VM (create a new VM from that snapshot instead). A snapshot needs cloud-init and should be cleaned with `cloud-init clean` before it is taken, or nothing runs and the API reports no error; an older snapshot with no recorded source VM cannot be refused, so this applies to it too. - Which image a cloud VM runs: GET /services/{id} returns image = { slug, name } (slug = catalog slug such as "debian-12", or your snapshot id, or null when not in the catalog), or image = null when it cannot be determined. It follows a reinstall. List responses carry it only for VMs that recorded it at create or reinstall. - 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 through the QEMU guest agent; returns data.status="reset-requested" (the platform 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). When it is false, capabilities.resetRootPasswordReason says why: "no_guest_agent" (the disk image has no guest-agent channel, e.g. restored from an older snapshot; the action answers 409 with a message starting "RESET_PASSWORD_UNSUPPORTED:" until you Reinstall) or "unknown" (could not be read just now; retry later). 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 VPS): 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..."} - Install selected library keys on the VPS: POST /services/{id}/ssh-keys/library/apply with {"keyIds":["7","9"]} (adds them; keys already installed stay; an empty list changes nothing; they take effect after the server is stopped and started) - cPanel hosting (category="hosting") usage + real connection facts: GET /services/{id} returns data.hosting = { username, serverHostname?, diskUsedMb?, diskLimitMb?, bwUsedMb?, bwLimitMb? } when the cPanel provisioning module reports a username (account provisioned). MB units are as the billing system reports them. Individual usage fields are OMITTED (not zeroed) when the panel didn't report them: never guess. FTP/SSH ports are intentionally NOT returned (shared-hosting shell access isn't guaranteed; ports 21/22 are not assumed real). To manage email/databases/files/FTP, mint a single-use SSO URL into the client-area product page (which surfaces the native "Login to cPanel" action): POST /services/{id}/panel-sso → {"url":...}. To deep-link straight into a specific cPanel app instead (skipping the client-area product page), use POST /services/{id}/cpanel-sso with an optional body {"app":"Email_Accounts"|"FileManager_Home"} → {"url":...}. Omit "app" for a plain cPanel-home login. Hosting (category="hosting") services only: a VPS/proxy id returns INVALID_PARAM. Any "app" value outside the two listed is rejected (INVALID_PARAM). - 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":""} - Enable object storage: POST /object-storage (idempotent; returns the account with its endpoint and price card) - Create a bucket: POST /object-storage/buckets {"name":"media","region":"eu-central-1","versioning":false} - Create an access key: POST /object-storage/keys {"name":"ci","scope":{"buckets":"*","access":"readwrite"}} → the response carries secretAccessKey ONCE; it is never retrievable again. - Use it: aws --endpoint-url https://s3.eu-central-1.rarestack.net s3 ls s3:// - Delete a bucket: DELETE /object-storage/buckets/{id}?confirm=[&purge=true] (confirm must equal the bucket name; without purge a non-empty bucket is refused with CONFLICT) - The container registry is live at registry.rarestack.net: pick a tier, enable it under a handle, create push or pull credentials, docker login and push/pull, and link your Kubernetes clusters. If it is ever paused, every registry write below (enable, tier change, close, credentials, cluster link/unlink/rotate, repository/tag/manifest deletion, the Kubernetes manifest) answers 503 BACKEND_UNAVAILABLE and changes nothing, the token endpoint issues no tokens (docker login fails), and POST /services with registry:{link:true} still creates the cluster but reports registry.reason "not_available". Reads of an account that already exists keep working. - List registry tiers and prices: GET /registry/tiers → {"items":[{"tier":"free","quotaGb":10, "burstCeilingGb":10,"monthlyCents":{"EUR":0,"USD":0},"overageCentsPerGbMonth":2, "overageCentsPerGbMonthByCurrency":{"EUR":2,"USD":2.28},"maxRepos":20,"available":true}, ...]} maxRepos is the most repositories the tier may hold. overageCentsPerGbMonth is EUR cents; the ByCurrency object adds the USD price (converted at the current rate, two decimals of a cent). Unauthenticated callers see ONLY tiers with available:true (all four while the registry is live, none while it is paused); a signed-in caller always sees all four, with available marked per tier. - Suggest a free handle: GET /registry/handles/suggest?base=acme → {"suggestions":["acme42","acme07","acme81"]} (up to 3, always free/valid/never reserved; base is optional and free-form; at most 60 requests per minute per account, else 429 RATE_LIMITED without Retry-After) - Enable the container registry: POST /registry {"handle":"acme","tier":"free"} (handle is customer-chosen and immutable; it becomes your image path prefix registry.rarestack.net/acme/) Before the body is read, the account must pass the cloud order balance rule (overdue cloud invoice refused; established accounts pass; any other account needs a positive balance covering the first month of what it already runs), else 400 INVALID_PARAM, e.g. "Not enough balance to order this. Please add funds to your balance and try again. Add funds here: ". Enable velocity: an attempt that reaches the actual enable, reopen or re-enable uses one from 3 per account and 10 per client IP per 24 hours (refilling gradually); a refusal before that step (bad or taken handle, already enabled) uses none. Over the limit: 429 RATE_LIMITED "Too many container registry enablement attempts on this account today. Please try again tomorrow." (or "... from this network today ..."), without Retry-After. - Create a push credential: POST /registry/credentials {"name":"ci","scope":"push"} → username "acme+ci", secret shown ONCE in the response. - docker login registry.rarestack.net -u acme+ci - docker push registry.rarestack.net/acme/app:1.0 - List registry credentials: GET /registry/credentials (never a secret; every credential, revoked ones included; add ?status=active for only the usable ones, neither revoked nor expired); revoke one: DELETE /registry/credentials/{id}. A revoked credential keeps its name, so reusing that name answers 409. The token endpoint (GET|POST /registry/token) is called automatically by Docker/OCI clients on login/push/pull: you never call it by hand. - GET /registry also returns usage {logicalBytes,repoCount,sampledAt} (null until first measured), quota {quotaGb,burstCeilingGb,overageCentsPerGbMonth,overageCentsPerGbMonthByCurrency:{EUR,USD},maxRepos} (push.repoCount of quota.maxRepos is "N of M repositories"), closedAt and deleteAfter (null unless the registry is closed), and push {allowed,reason}, reason explains why a push would currently be refused (over_ceiling, balance_under_72h, meter_stale_24h, repo_limit, suspended, ...) before you try one. suspended means the registry account is suspended: pulls keep working, pushes are refused until the suspension is lifted (contact support). repo_limit means new repositories are refused (you are at your tier's repository count cap); pushes to a repository you already have keep working. The cap counts the account's repository index (usage.repoCount itself is the hourly sample). A repository counts from the moment push to it is granted, and keeps counting with no tags. A repository deleted through the API keeps counting until the registry has really removed it (about 8 days); pushing that name again meanwhile reuses its slot. A granted repository never pushed frees its slot after its one-hour hold, once a later push-token request or the hourly registry check finds the registry does not hold it. If the registry cannot confirm whether a repository not yet in the index exists, push to it is refused for that request (repositories already in the index always keep push). balance_under_72h is one of the two refusals a balance still drives: a push needs enough spendable credit (bonus + credit minus this month's uninvoiced usage) to cover 72 hours of your current accrual, and, until the account has made two payments and is at least 38 days old, creating or growing a cloud resource needs a spendable balance covering its first month (an account past that point with no overdue cloud invoice orders without a balance). What already runs is postpaid, metered then invoiced; the push rule is a deliberate cap on exposure and it stays until tier limits replace it. Registry STORAGE is metered and invoiced like the rest of the cloud either way. - Change tier: PATCH /registry {"tier":"starter"} (upgrades always allowed; a downgrade below your current measured usage is refused with CONFLICT tier_below_usage) - Close the registry: DELETE /registry?confirm= → 202 {"status":"closed","deleteAfter":...}. Storage is NOT deleted immediately, POST /registry with the SAME handle reopens it before deleteAfter. GET /registry on a closed registry returns the same closedAt and deleteAfter, so the date survives a reload. Past deleteAfter the storage is purged for good, but the account is not lost: POST /registry still works (200) and RE-ENABLES it, reusing the same handle (reclaimed) or, if you name a different one, claiming it as long as it is currently free. The tier in that request applies fresh; nothing carries over from before the close. - List repositories: GET /registry/repositories (paginated: limit/cursor) - One repository + its tags: GET /registry/repositories/{repo} (each tag carries CVE severity counts). A tag's createdAt (always present, null when the image carries none) is the image BUILD time (OCI created), not the push time. pushedAt is a deprecated alias of createdAt: the image's build time; the registry exposes no push time. The repository list's lastPush is documented the same way: a deprecated name for the newest image's build time (OCI created). - Delete an entire repository: DELETE /registry/repositories/{repo} → 202 {"deleted":, "pendingGc":true}. pendingGc is always true: the API cannot list untagged images (left by a tag delete, by pushing a tag again, or by docker/oras), and they stay pullable by digest until the registry removes them, about 8 days (7-day retention plus the daily cleanup). A repository with no tags left still answers 202 with deleted 0 (repeating it writes at most one audit entry per 10 minutes). Only a repository the registry no longer holds at all answers 404. - Delete one tag (removes the tag reference only; other tags, indexes and the image itself are untouched, and an image left without tags is removed by the registry after about 8 days; delete it by digest to remove it now): DELETE /registry/repositories/{repo}/tags/{tag} - Delete an image by digest (untags every tag pointing at it, pass ?confirm=true if more than one does): DELETE /registry/repositories/{repo}/manifests/{digest} Destructive: it removes the manifest and every tag pointing at it. confirm=true is required when more than one tag points at it at request time. A tag pushed while the request is in flight is removed as well; the returned tags are the ones seen at the last check before the delete. → 202 {"deleted":1,"tags":[...]}. Without confirm the 409 message names the tags: "This digest is referenced by 2 tags (v1, latest). Pass confirm=true to delete it anyway." (at most 10 named, then "and more"; error.details lists every tag). - CVE findings for one tag: GET /registry/repositories/{repo}/tags/{tag}/vulnerabilities (paginated) - Link a Kubernetes cluster you own to the registry: POST /registry/clusters/{serviceId} → 202 {"link":{"serviceId":...,"status":"linking","credentialName":"k8s-1a2b3c4d", "secretName":"rarecloud-registry-credentials","installs":[...]},"disclosure":"..."} Installs a small controller (rarecloud-registry-syncer) with cluster-wide Secret/ServiceAccount write access, fanning the pull secret out to every present and future namespace except kube-*/gardener*/monitoring and anything labelled rarecloud.io/registry-secret=disabled; 409 already_linked on a repeat call; unreachable cluster stays "linking", the hourly reconciler finishes it. - List linked clusters: GET /registry/clusters → {"items":[{serviceId,clusterName,status, installedAt,syncerImage,syncerReady,syncerCheckedAt,lastError,credentialName}]} (credentialName is the pull credential's name, the cluster's serviceId such as "k8s-1a2b3c4d" (links made before 2026-10-12 keep a "k8s-k8s-1a2b3c4d" style name), never the secret itself; null before the first successful link) - Rotate a linked cluster's pull credential: POST /registry/clusters/{serviceId}/rotate → 202 {"status":"active"|"rotating","credentialName":...}; 409 rotation_in_progress on a second call while one is running; 503 cluster_unreachable leaves the OLD credential still active. - Unlink a cluster (removes everything the syncer installed, revokes the credential): DELETE /registry/clusters/{serviceId} → 202 {"status":"unlinking"|"unlinked"} (idempotent: a repeat call while still unlinking is a no-op 202). - Prompt at cloud-k8s create time: POST /services {"category":"cloud-k8s",..., "registry":{"link":true}} → the response echoes registry:{"linked":true,"status":"linking"} (or {"linked":false,"reason":"not_enabled"|"link_failed"|"not_available"}; not_available means the registry is paused, no link was recorded, the cluster itself is still created). - A cluster you manage yourself (BYO, not linked): POST /registry/docker-credentials/kubernetes (query: scope=pull|push, expiry=30d|90d|1y|never, namespace, secretName) → a ready-to-apply Secret manifest (kubectl apply -f), or Accept: application/json for the same credential and manifest as structured JSON. Same Secret shape the syncer installs, just unmanaged: apply and rotate it yourself. Console: the Container Registry page covers enable, overview, credentials, repositories, tier change and close. Kubernetes cluster linking also has console coverage: the cluster-create wizard shows a checked-by-default "Link the container registry" step (the same POST /services registry:{link} field above) when the account has a registry, or a short inline hint when it does not; every cluster's own page also carries a registry card (status, syncer readiness, credential name, Unlink/Rotate with confirm) regardless of how it was linked. - List your snapshots: GET /snapshots/ - Snapshots of one cloud VM: GET /services/{id}/snapshots/ - Take a snapshot: POST /services/{id}/snapshots/ with {"name":"before-upgrade"} Cloud VMs only (a legacy VPS id returns NOT_FOUND; legacy VPS backups live in the VPS control panel). The VM keeps running. It returns immediately: the snapshot is usable within seconds ("securing") and reaches "ready" once fully independent. Up to 5 per VM. "usedBytes" is null until measured, and that measured figure is what is billed. - Restore a VM from its own snapshot: POST /services/{id}/restore/ with {"snapshotId":""} DESTRUCTIVE: the disk is replaced and everything written since is lost. The snapshot must be one taken from that same VM. Refused with 409 like reinstall while the VM's status is error ("SERVER_IN_ERROR_STATE:") or not settled ("SERVER_STATE_UNCONFIRMED:"). - Delete a snapshot: DELETE /snapshots/{id}: blocked (CONFLICT) while VMs created from it still exist; the error names them. Deleting a VM or reinstalling it is blocked while one of its snapshots is still securing. - List load balancers: GET /load-balancers/ - Create an L4 LB: POST /load-balancers/ with {"name":"web-lb","port":80,"memberServerIds":[""]} (EUR 9/month with its public IP, billed hourly; duplicate ids ignored; at most 50 distinct VMs per create, more is 400 INVALID_PARAM; add more later with POST /load-balancers/{id}/members). Asynchronous: it answers at once with status "pending"; poll GET /load-balancers/{id} until "active" (a few minutes). Do NOT create it again to retry: send an Idempotency-Key instead. A public IP detached from a load balancer is billed as a reserved IP again (EUR 2/month). - Delete an LB: DELETE /load-balancers/{id} ("deleted" at once, or "deleting" while it was still being built; then GET answers 404 when it is gone) - List LB members: GET /load-balancers/{id}/members/ - Add a member: POST /load-balancers/{id}/members with {"serverId":"","port":8080}. The member address is the VM's private IP on the LB's network when it has one there, otherwise its first fixed IP (usually public). When the VM's private interface carries the Private network firewall, the platform keeps one rule there for this load balancer (tcp, its port, from the VIP's subnet), ensured on every add, shared with the account's other load balancers on the same port and subnet, and removed when the last of them is deleted, so the member is reachable on that port without opening it publicly. If the VM's ports cannot be read, the add answers 503 ("The VM's network ports could not be read. Please retry shortly.") and nothing is added; it never falls back to the public IP on an error. If the load balancer's rule on the Private network firewall cannot be ensured, the add answers 503 ("The load balancer's firewall rule could not be ensured. Please retry shortly.") and nothing is added; at build time that failure retries and then ends the build in error. Idempotent: the same VM on the same port returns the existing member's id (200) and adds nothing; a member Octavia left in ERROR does not count. - Remove a member: DELETE /load-balancers/{id}/members/{mid}. Add and remove answer 409 CONFLICT ("The load balancer is still being set up. Retry when it is active.") while the load balancer's build has not finished, 409 CONFLICT ("The load balancer is being deleted. Its members can no longer be changed.") once its delete was accepted, and 503 BACKEND_UNAVAILABLE with Retry-After when another change to this load balancer is in progress ("Another change to this load balancer is in progress. Please retry shortly.") or its members or state could not be read; then nothing was changed, retry after Retry-After seconds. - Network model: the private network is open between the resources of the same account where the platform has applied it, through the account's Private network firewall (isPrivateNetwork: true in GET /firewalls, name "Private network"). The platform applies it to the private interface of the account's VMs only, never to the public interface. Its managed rule names the firewall itself (remoteFirewallId equal to the firewall's id): it admits the account's own VMs, the private interfaces that carry it, on any protocol and port (OpenStack enforces such a rule as the set of those interfaces' addresses: a packet is admitted when its source address is one of them). So VMs that carry it reach each other privately on any port, and another account's VMs are not admitted. Traffic to a Reserved IP (and a legacy floating IP) arrives on the private interface, where this firewall admits it only when its source address is one of those interfaces; a packet from the internet that forges such an address is admitted the same way (before this firewall existed, such a packet reached only the ports your other firewalls open), and the platform adds no filtering against it. Each load balancer gets one more rule when built or when a member is added (tcp, its port, from the subnet its VIP sits on; description "rarecloud: load balancer port "); load balancers with the same port on the same subnet share one such rule, removed when the last of them is deleted. Rules you add: an inbound rule needs a remoteCidr inside 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 100.64.0.0/10 (missing, public or 0.0.0.0/0 → 400 INVALID_PARAM; outbound rules are not restricted); such a rule admits a whole range, where the managed rule admits only your own interfaces' addresses. Its rules are editable to restrict private traffic; the platform never re-adds a rule you removed (the load balancer rule excepted: the next member add or build ensures it again). A rule shows either remoteCidr or remoteFirewallId, never both. Firewalls only add up: the default firewall (icmp + tcp 22/80/443 from anywhere) and any other attached firewall also apply on the private interface, so restrict those ports in them. It is ingress-only by construction: it has no outbound rules of its own, so it never widens what the private interface may send and your other firewalls decide outbound traffic; outbound rules you add to it are not restricted (any destination, 0.0.0.0/0 included) and add to what your other firewalls allow. Attach, detach and delete of it answer 409 CONFLICT (attach would put it on the public interface too); its attachedServerIds lists the VMs whose private interface carries it (read-only). Which VMs carry it: new VMs get it when their private interface is created; a VM moved to another VPC gets it only if its old private interface still carried the default firewall (otherwise its firewalls are copied unchanged); VMs created before it was introduced get it when the platform's one-time update reaches the account (until then: only the ports their firewalls open, by default the default firewall's icmp + tcp 22/80/443); a VM whose private interface no longer carries the default firewall (replaced by the user) is left as set; a VM where it could not be applied at create admits only the ports its firewalls open until an operator applies it. Attaching or detaching other firewalls never removes it. It counts toward the security group and rule quotas like any firewall. Public traffic is filtered by your other firewalls; a member on a public IP needs its port opened there. - List VPCs: GET /networks/ - Create a VPC: POST /networks/ with {"name":"staging"} (no firewall rule is added: the Private network firewall's managed rule admits your VMs whatever network they are on; the firewall itself is created now if the account has none yet; other firewalls unchanged) - Delete a VPC: DELETE /networks/{id} (no firewall rule is changed; there is no per-VPC rule) - VPC create/delete can answer 503 BACKEND_UNAVAILABLE with Retry-After ("A network change is in progress, retry in a few seconds.") while another network change on the account runs: nothing was changed; wait Retry-After seconds and retry (same Idempotency-Key for a create). Other 503s carry no such guarantee: a delete may have removed part of the network (retry the delete); "No free VPC range left" does not clear by retrying. - POST /services answering a 503 other than "A network change is in progress" does not say whether the create happened (a VM may be building): list services before retrying. A client that automatically retries a 503 BACKEND_UNAVAILABLE carrying Retry-After (the current rarecloud CLI and Terraform provider do) can create a second resource in that case; check GET /services after such a retry. - Move a VM into a VPC: POST /networks/{id}/vms with {"serverId":""} (the new private interface keeps the old one's firewalls; it gets the Private network firewall only if the old one still carried the default firewall) - List firewalls: GET /firewalls/ (each: id, name, isDefault, isPrivateNetwork, inboundCount, outboundCount, attachedServerIds; one "default" firewall is the per-account baseline applied to every VM: editable, not deletable; the "Private network" firewall (isPrivateNetwork: true) is applied automatically to private interfaces: rules editable, inbound sources private only, no outbound rules of its own; not attachable, detachable or 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; names need not be unique; "default" is reserved, 400 INVALID_PARAM; the only 409 is IDEMPOTENCY_IN_PROGRESS; an exhausted security group quota answers 502 BACKEND_BAD_RESPONSE) - Get one (rules + attachments): GET /firewalls/{id} → {inbound[], outbound[], attachedServerIds} - A rule description may not start with "rarecloud:" (reserved for the rules the platform manages; 400 INVALID_PARAM). - 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; remoteCidr defaults to 0.0.0.0/0, but an inbound rule on the Private network firewall needs a private range, e.g. 10.0.0.0/16, else 400 INVALID_PARAM, a missing remoteCidr included) - Remove a rule: DELETE /firewalls/{id}/rules/{ruleId} → the firewall with its remaining rules. Any rule can be removed, the Private network firewall's managed rule included (then your VMs reach each other privately only on ports your other firewalls open; no API request adds it back). Never 409; 404 "Firewall not found." or "Rule not found." - Attach a firewall to a VM: POST /firewalls/{id}/attach with {"serverId":""} (applies it to every interface of the VM; the Private network firewall → CONFLICT) - Detach: POST /firewalls/{id}/detach with {"serverId":""} (the Private network firewall → CONFLICT) - Delete a firewall: DELETE /firewalls/{id} (the default firewall, the Private network firewall, or one still attached to a VM, can't be deleted → CONFLICT) - Credit balance: GET /billing/credit/ - Top up credit: POST /billing/credit/top-up with {"amountCents":1000} (scope billing:write; minimum 10 in the account currency, e.g. EUR 10; returns a paymentUrl for the human to pay) - Cloud billing state and the dated schedule: GET /billing/state (state ok|suspended; openInvoice = the oldest UNPAID invoice we issued for your cloud usage, as {id, amountCents, currency, dueAt}, or null when you owe nothing. That invoice is what the calendar runs on: you have 7 days to pay it, counted from the day it is ISSUED, so one issued on the 1st is due on the 7th (dueAt, the last day to pay) and still unpaid your cloud resources are powered off on the morning of the 8th; 7 days after the power-off they are deleted. An invoice issued before 2026-11-11 states its issue day as dueAt and keeps the same 7 days from that day. suspendAt is that power-off and deleteAt that deletion, both held to your own 09:00-20:00 local window, so suspendAt is the deadline to act on. A renewal for a VPS, proxy, hosting or domain is never reported here and never powers off a cloud resource. availableCents and currency, accruedMonthCents, burnCentsPerHour = fractional cents per hour in that same currency, runwayHours = how long the balance lasts at that burn, suspendedCount: all INFORMATION, none of them suspends anything. (A balance gates two actions: creating or growing a cloud resource, until the account has made two payments and is at least 38 days old, needs a balance covering the plan's first month; and a container registry push needs 72 hours covered, refused with balance_under_72h. Neither refusal suspends anything.) Credit you hold settles a cloud invoice automatically, so an open invoice means the credit did not cover it. A money field is null when the billing backend could not be read: unknown, not zero. graceEndsAt is always null and state never answers grace: both are kept only for clients built against the older billing model.) - How cloud usage is billed: metered hourly and invoiced at the end of the month. Until you have paid us twice you are also invoiced mid-month for what you have used so far, so your first invoices arrive on the 15th and the 1st; after that, on the 1st only. Anything under 5 EUR is not invoiced on its own: it rolls into the next invoice. A resource is billed for as long as it EXISTS, whatever its power state, including while the account is suspended; only deleting it stops the meter. - Billing alert: GET /billing/alert, PUT /billing/alert with {"thresholdCents":5000} and/or {"thresholdDays":3} (1 to 60 days: you are emailed once a day while your runway is under that many days), DELETE /billing/alert to remove it. Omit a field to keep the stored value, send null to clear it; at least one threshold must remain set. Setting a threshold arms the alert: with no "enabled" in the body, enabled defaults to true, so sending only a threshold re-enables a disabled alert (an enabled-only body, or one that just clears a threshold, leaves the flag as stored). runwayHours is filled in only when thresholdDays is set. This object is uniformly EUR; the burn rate and the client-currency figures live on GET /billing/state. - 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 (the billing system's payment 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"} - Connected sign-in accounts (Google, GitHub): GET /account/social-identities (your own account only; console session only, an API token gets 403 FORBIDDEN; returns [{provider, email, providerLogin, linkedAt, lastLoginAt}], where email is the address the provider verified when it was connected and providerLogin is the provider account's handle then (GitHub login, Google email; null when unknown)). Connecting is done in the console (Account, Security), not through the API. - Disconnect a sign-in account: DELETE /account/social-identities/{provider} (provider is google or github; console session only, an API token gets 403 FORBIDDEN; not connected → NOT_FOUND). You can always sign in with your email and password: an account created with Google or GitHub has no password until Forgot password sets one. - 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 (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":""}]} - Reply to a ticket: POST /tickets/{id}/replies with {"body":"..."}. A reply on a closed ticket reopens it (status becomes awaiting-staff). - Invoices: GET /billing/invoices, GET /billing/invoices/{id}, GET /billing/invoices/{id}/pdf. Ledgers: GET /billing/credit/ledger, GET /billing/bonus, GET /billing/bonus/ledger. Voucher: POST /billing/vouchers/redeem {"code":"..."}. - Reserved IPs: GET and POST /reserved-ips, DELETE /reserved-ips/{id}, POST /reserved-ips/{id}/attach, POST /reserved-ips/{id}/detach. - Volumes: GET and DELETE /volumes/{id}, POST /volumes/{id}/detach. Backups: GET and POST /services/{id}/backups. ISO: GET, PUT and DELETE /services/{id}/iso. Hostname, tags, password: POST /services/{id}/hostname, PUT /services/{id}/tags, POST /services/{id}/password. Cancel: POST /services/{id}/cancel. Upgrade: GET and POST /services/{id}/upgrade. - Proxy management: GET /proxies/catalog, POST /proxies/{id}/auto-renew (ISP, ISP Proxies Global and mobile), POST /proxies/{id}/rotate, POST /proxies/{id}/format, GET and PATCH /proxies/{id}/auth, GET and PUT /proxies/{id}/auto-rotation, GET and POST /proxies/{id}/replacements. - Residential Proxies Global: GET /proxies/residential-global/catalog, GET /proxies/residential-global/geo/{countries,regions,cities,asns}, GET /proxies/{id}/credentials, POST /proxies/{id}/credentials/rotate, GET /proxies/{id}/bandwidth, POST /proxies/{id}/top-up, GET and PUT /proxies/{id}/auto-top-up. - ISP Proxies Global: GET /proxies/isp-global/catalog, GET /proxies/isp-global/location-countries, GET /proxies/isp-global/locations, GET /proxies/{id}/locations, GET /proxies/{id}/ips, GET /proxies/{id}/usage, POST /proxies/{id}/ips/place, POST /proxies/{id}/ips/location, POST /proxies/{id}/ips/{proxyId}/location. - Object storage: GET /object-storage/regions, GET /object-storage/usage, DELETE /object-storage/keys/{id}. - Responses use an {ok, data} envelope; errors use {ok:false, error:{code,message}}. - 503 MAINTENANCE_IN_PROGRESS: a maintenance window pauses creating cloud VMs, reinstall, snapshot restore, resize, moving a VM to another private network, volume attach/detach, load balancer create and Kubernetes create/pool/scale changes (a window that includes storage also pauses volume and snapshot creation). Nothing was created or changed. Do not retry in a loop: wait until the time in the message (Retry-After gives the seconds), or poll GET /maintenance (public). Running resources, reads, deletes, power actions and firewall changes keep working. - 403 ACCOUNT_ORDERING_BLOCKED on any create/order: new orders are not accepted on this account; do not retry, tell the human to contact support. Our team can pause new orders on an account (message "New orders are paused on this account. Please contact support."), and an account in a country we do not take new orders from gets "New orders are blocked on this account. Contact support." A suspended service does not block new orders. Existing services, renewals, payments and tickets keep working. A quota increase request (POST /limits/requests) is refused only by such a pause. ## AI code sandboxes AI Sandboxes are available in beta. `xs` (1 vCPU / 1 GB, EUR 0.052 per hour) and `s` (1 vCPU / 2 GB, EUR 0.064 per hour) are available today. The larger sizes (`m` to `2xl`) and custom shapes above 1 vCPU / 2 GB answer 409 `size_unavailable` until capacity is extended; `GET /sandboxes/sizes` reports which sizes are available right now (`available`, plus `custom.maxAvailableVcpu` and `custom.maxAvailableRamGb`). If the sandbox backend is switched off, every route below answers 503 BACKEND_UNAVAILABLE "AI Sandboxes are not available yet."; tell the user that, rather than retrying. Returns 503 SANDBOX_LAUNCH_GATE_CLOSED while the launch gate is closed: the sandbox backend is on but AI Sandboxes are not launched for your account ("AI Sandboxes are not launched yet."). The gate is open today, but it can be closed again; while it is open AI Sandboxes are available. Every route below, except `DELETE /api/v1/sandboxes/{id}` (`DELETE /sandboxes/{id}` on https://api.rarecloud.io/v1), answers it before anything is read or changed; tell the user, do not retry. Deleting your own sandbox always works, so billing can always be stopped. A `sandboxes` limit request (POST /limits/requests) answers it too, and GET /limits then shows `sandboxes: null`. Ephemeral, isolated execution environments for AI agents (like E2B), under `POST /sandboxes`. Create one from a template (`python` with the data-science stack, `node`, or `base` for shell only) with an optional `timeoutMs` lifetime (default 5 minutes, max 1 hour; a value from 1000 ms to one minute is raised to one minute; below 1000 ms answers 400 INVALID_PARAM), then: - Sizes: pick the resources with an optional `size`, independent of the template (the template is the image): `xs` 1 vCPU / 1 GB, `s` 1 vCPU / 2 GB, `m` 1 vCPU / 4 GB, `l` 2 vCPU / 8 GB, `xl` 4 vCPU / 16 GB, `2xl` 8 vCPU / 32 GB, all with 3 GB of disk. Without `size` a sandbox gets its template's default size: `xs` for base, `s` for python and node (the resources and price each template had before sizes, so a client that never sends `size` keeps its price). The price is EUR 0.040 per vCPU-hour plus EUR 0.012 per GB-hour, billed per second (s is EUR 0.064 per hour, l EUR 0.176). An unknown size answers 400 INVALID_PARAM. Not every size runs: available sizes depend on the cluster ceiling; GET /sandboxes/sizes reports availability. A size that is not available answers 409 CONFLICT with details `{field: "size", message: "size_unavailable"}`; the same 409 ("This sandbox shape is not available on the cluster right now; pick a smaller size.") answers when the cluster refuses the sandbox, and retrying it unchanged does not help. A sandbox reads back its `size`, `vcpu` and `ramGb`. - Custom resources: instead of a size, send explicit `vcpu` (1 to 8) and `ramGb` (1 to 32, between 1x and 8x the vCPU), like `{"vcpu":2,"ramGb":12}`. Send either `size` or both `vcpu` and `ramGb`: mixing them, or one of the two alone, answers 400 INVALID_PARAM, and so does a number out of bounds. Same price formula, same 409 size_unavailable for a shape the cluster cannot run yet and same account caps; the sandbox reads back `size: null` unless the shape equals a size, and the invoice line reads "2 vCPU / 12 GB". The `custom` block of `GET /sandboxes/sizes` carries the bounds and the EUR per-unit rates (`vcpuCentsPerHour`, `ramGbCentsPerHour`), plus `maxAvailableVcpu` and `maxAvailableRamGb`: the largest shape one sandbox can get today (above them a create answers 409 size_unavailable). - `GET /sandboxes/sizes` lists the sizes with `vcpu`, `ramGb`, `diskGb`, the price per hour (`hourlyCents` in EUR, `hourlyCentsByCurrency`, `accountCurrency` and `accountHourlyCents`), `default` (true for s, the size a create with neither `template` nor `size` gets) and `available` (false while the cluster ceiling does not admit the size), plus `defaultSize` (s). Each template's own default is `defaultSize` on `GET /sandboxes/templates`. - `GET /sandboxes/templates` lists the templates with their default size (`defaultSize`, and its `vcpu`, `ramGb`, `diskGb`), the image each runs and the price per hour at that size in EUR and USD (`hourlyCents` is EUR, `hourlyCentsByCurrency` has both), plus the caller's own: `accountCurrency` (USD for a USD account, EUR otherwise) and `accountHourlyCents` in that currency; read it to show a price before you create anything. - Optional create fields: `name` (1 to 63 lowercase letters, digits and dashes; unique among your live sandboxes, a name in use answers 409 with details `{field: "name", message: "name_taken"}`), `env` (at most 50 variables; a name matches `^[A-Za-z_][A-Za-z0-9_]{0,127}$`, a value is at most 8192 bytes and all values together at most 65536 bytes), `labels` (at most 20; a value is at most 256 characters) and `networkBlocked: true` (outbound network off, fixed at creation). Env values are write-only: they are never returned. A sandbox reads back its `name`, `image`, `labels`, `envKeys` (the variable names only) and `networkBlocked`. Listing and reading answer 503 when the session ledger behind those fields cannot be read; retry. - A create with `env` can answer 503 ENV_UNAVAILABLE (no Retry-After): the sandbox cluster refused the environment variables. No sandbox was created and nothing is billed; create it without `env`, or try again later. - `POST /sandboxes/{id}/run_code` with `{language: "python"|"node", code}` returns `{stdout, stderr, exitCode}`. - `POST /sandboxes/{id}/commands` with `{cmd}` runs a shell command. - Run mode: `POST /sandboxes` with `run: {}` starts the image's own program; `run: {command: [...]}` replaces the image's command (its entrypoint still runs), `run: {entrypoint: [...], command: [...]}` replaces both. A template has no program of its own, so with a template `run.command` is required (400 INVALID_PARAM, detail `command_required`). The sandbox ends when the program exits: status `exited` with `exitCode`; billing stops at the exit time. There is no restart. Commands and files still work while it runs. Without `run` the sandbox waits for your code and commands, as before. Limits: at most 64 elements per list, each at most 4096 bytes, 32 KiB in total. - `GET /sandboxes/{id}/logs?tail=N` (`GET /api/v1/sandboxes/{id}/logs` on the console mirror; default 200, at most 5000) answers the last lines of the program's output as plain text: from the running container, or after an exit from what was kept (the last 256 KiB, for 24 hours). An exited sandbox stays in the list until then; DELETE removes it and its kept logs. In run mode the root filesystem is writable, but the sandbox still runs as a non-root user: an image that needs root exits with an error and says so in its logs. - run_code and commands stop at 10 MiB of output (stdout and stderr together) and after 300 seconds (or at `expiresAt`, if sooner). A cut-off result has `truncated: true` (plus `timedOut: true` for the time limit) and exitCode -1. In the template images the command is killed at the time limit; in a custom image the API only stops waiting and the command may keep running until it ends or the sandbox expires. - At most 4 run_code, commands or file calls run at once per account (a per-server limit applies too); more answer 429 RATE_LIMITED with Retry-After. - `GET/PUT /sandboxes/{id}/files` reads and writes files by absolute path, up to 25 MiB per file (413 PAYLOAD_TOO_LARGE above it). A read answers text for any valid UTF-8 file without a NUL byte, or base64 with `encoding: "base64"` for a binary file (invalid UTF-8 or a NUL byte) and for text dense in control characters (its JSON-escaped form would be more than twice the file's size); always check `encoding`. A write takes the same `encoding` field; base64 must be canonical (standard alphabet, `=` padding, length a multiple of 4), anything else answers 400 INVALID_PARAM. - A sandbox reads back `startedAt` (when it actually started running, which is when billing starts; null while pending) and `endedAt` (when it ended: exited, or `expiresAt` once past its lifetime; null while it lives). - `DELETE /sandboxes/{id}` deletes it; billing stops when the delete is accepted. A 503 on delete means the sandbox may still run: retry. Every sandbox also stops and is deleted automatically at `expiresAt`, which the server computes from `timeoutMs` at creation and returns; the sandbox is told to shut down at that exact time, and billing and the concurrency limit stop there whatever the cluster does. Past it the sandbox reads `terminated` and refuses run_code, commands, and file reads and writes (409). - Preview URLs are not available: a sandbox accepts no inbound connections, and `POST /sandboxes/{id}/ports/{port}` answers 501 NOT_IMPLEMENTED. - A custom `image` must come from a supported public registry: Docker Hub (`nginx:1.27`, `docker.io/...`), `ghcr.io`, `quay.io`, `registry.k8s.io`, `public.ecr.aws`, `gcr.io` or `mcr.microsoft.com`, with no port. Anything else answers 400 INVALID_PARAM. There is no image size check: a very large image is bounded only by the cluster's storage limits and may fail to start. - Or a private image from your own RareCloud container registry, under your own handle: `registry.rarestack.net//:` or `...@sha256:` (the hostname GET /registry reports, without a port). A tag or a digest is required; `latest` is refused unless a digest is given. The tag is resolved at creation and the sandbox runs the image pinned to its digest (its `image` reads `/@sha256:`). The API mints a pull-only credential for that sandbox alone (one repository, revoked when the sandbox ends); you create nothing. A refusal is 400 INVALID_PARAM with details `{field: "image", message: }`: registry_port_not_supported, registry_not_launched (a 400 here; the registry routes answer 503 for the same state), registry_not_enabled, registry_not_active, not_your_registry, tag_required, image_not_found, invalid_image_ref or unsupported_digest (only sha256 digests are supported). - A pending sandbox may carry `statusReason`: `pulling_image` while its image is pulled, `image_pull_failed` when it cannot be pulled. One still in `image_pull_failed` 2 minutes after creation is ended automatically (never billed); fix the image and create a new one. - Scopes: listing and reading sandboxes and reading files need `services:read`; creating, deleting, run_code, commands and file writes need `services:write`. Billing is per second, from the moment it is running (its true start, whether or not anyone looked at it) until it is deleted or its lifetime ends, on the monthly cloud invoice in the account's currency. A sandbox that never starts is not billed. A 503 on create after a timeout does not prove nothing was created: list the sandboxes before retrying, and delete the one you do not need (it is billed). Creating one goes through the same order guard as every other cloud resource: an account that is not established needs a balance that covers the requested lifetime, and an account that cannot pay gets 400 INVALID_PARAM "Not enough balance to order this ..." with an add-funds link (an agent cannot pay; pass the message and link to the account owner). An account runs at most as many sandboxes at once as its limit (default 8; one past its `expiresAt` no longer counts); the next create answers 409 QUOTA_EXCEEDED. The limit is in `GET /limits` (`sandboxes`) and is raised like any other limit. The running sandboxes of an account together use at most the lower of 16 vCPU / 64 GB and the room the account's sandbox limit admits (1 vCPU and 2 GB per allowed sandbox): 8 vCPU and 16 GB at the default limit of 8. Past that a create answers 409 QUOTA_EXCEEDED with details `{field: "sandbox_vcpu"}` or `{field: "sandbox_ram_gb"}` carrying `required` and `available`. Pick a smaller size or end a sandbox. Sandboxes are tenant-isolated: another account's sandbox id answers 404. In development the backend may answer in mock mode, in which case every response carries `mocked: true`; do not treat mocked output as a real execution. ## Quota limits the user will hit Every account has per-resource quota limits (vCPU, RAM, instances, volumes, disk gigabytes, floating IPs). `GET /limits` returns them together with live usage and a per-resource state (`ok`, `warn` from 80%, `danger` from 95%, `unknown` when the region could not be read). Check it BEFORE proposing a deployment: a cluster or VM that does not fit is refused, and it is far better to tell the user up front than to have provisioning fail part-way through. A resource marked `unavailable` means we could not read it: that is not the same as "nothing used", so do not treat it as free headroom. The same response carries `registry`: the container registry's tier, status, `storedBytes` (last hourly measurement), `quotaGb`, `burstCeilingGb` (where pushes stop), `repoCount` and `maxRepos` (repository slots used of the tier's limit). It is null when the account has no registry, or when it could not be read just now. The same response carries `sandboxes`: running sandboxes (`used`) against the account's `limit` (how many may run at once, default 8) with the same `state`. `clusterCap`, when present, is the number that can run for now while a raise is being applied. Ask for more with `POST /limits/requests` `{requested: {sandboxes: N}, reason}` (1 to 200): every request opens a support ticket and our team reviews it. It is null when AI Sandboxes are not available. A quota request (from `POST` or `GET /limits/requests`) carries its support ticket as `whmcsTicketId` (the id for `GET /tickets/{id}`) and `whmcsTicketNumber` (the number Support shows, e.g. `ABC-123456`; null on older requests). Quote the number to the user. Sending a new request while one is pending replaces it and posts the new numbers on the same ticket; the decision arrives as a reply on that ticket and by email. For a managed-Kubernetes cluster, do the arithmetic with `POST /limits/estimate` rather than by hand: send the worker pools (`machineType`, `minimum`, `maximum`) and it answers with `fits` (do the minimums fit, i.e. will the deploy start at all), `shortfall` (what is missing, keyed exactly as a limit-increase request should be), and per pool how many nodes are actually `reachable` out of the `configured` maximum plus the resource that is `limiting` it. A pool whose minimum fits but whose maximum does not is fine: it deploys and it autoscales, just not as far as configured. `available: false` means we could not work it out: that is unknown, not "does not fit". Limits are raised by asking: the console has a "Request limit increase" form (Cloud → Limits). Every request opens a support ticket and is reviewed by our team; the new limit applies once it is approved. ## Billing model the user will ask about Cloud is POSTPAID for what already runs. Resources are metered hourly and then invoiced. Creating or growing one is prepaid until the account has made two payments and is at least 38 days old (the balance must cover the plan's first month); after that, with no overdue cloud invoice, it needs no balance. A credit balance is not what keeps a running resource alive. The invoice comes at the end of the month, and also mid-month until the account has paid us twice, so the first two invoices land on the 15th and the 1st. Anything under 5 EUR is not invoiced on its own: it rolls into the next invoice. Credit you do hold settles an invoice automatically the moment it is raised, so a funded account never sees a payment step. Each Cloud VM is still capped at its plan's monthly price, so an hour-by-hour VM never costs more in a month than the monthly price. An invoice gives the account 7 days to pay it, counted from the day it is issued: one issued on the 1st is due on the 7th. Still unpaid after its due date, its cloud resources are powered off until the invoice is paid, at 09:00 in the account's own time zone the next morning, and they are deleted 7 days after the power-off. A resource is billed for as long as it EXISTS, whatever its power state, including while the account is suspended: only deleting it stops the meter. Paying the invoice starts everything again. Classic hosting (VPS, cPanel, proxies, domains) is unchanged: fixed-term and paid in advance. A renewal there is never part of this calendar and never powers off a cloud resource. *Last updated: November 2026.*