EQVPS — VPS and code sandboxes for AI agents

Cancel a VPS. DEFAULT `end_of_period`: the server stays active until the end of the already-paid period, then is simply not renewed — NO data loss now, safe. `immediate` DESTROYS the VM and ALL data right away, permanently and irreversibly, and REQUIRES `confirm` set to the exact server hostname (see get_vps_status). Use end_of_period unless you explicitly intend to wipe the server now. On `immediate`, the unused portion of the already-paid period is refunded to your account balance (see `refund_amount` in the response). Already scheduled end_of_period? Call `undo_cancel` to keep the server, or call cancel_service again with type=immediate + confirm to switch to immediate destruction (refund as above). get_vps_status shows `cancellation` {type, cancel_at, can_undo}. Requires: token + reason; immediate also needs confirm=hostname. Typical: 409 cancellation_already_scheduled → undo_cancel, or repeat with type=immediate.

Switch a VPS to another plan IN PLACE — files and the OS are kept; the server reboots once (~1 min). `target_plan` = product_id from get_upgrade_options. The prorated difference is charged from the prepaid balance right away (402 with needed/balance if it is short — top up and retry); convert_to_nat refunds the unused difference to the balance. The next renewal uses the new price. Same function as the cabinet's Upgrade panel. If the server's host has no free room (or no free IPv4 for NAT → IP) right now, the response is 202 with `queued: true`: the difference is charged now and the upgrade is applied automatically from the queue, usually within 24 hours — the server reboots once at that moment and keeps running on the current plan until then; a second change_plan meanwhile returns 409 `upgrade_queued`. The response shows charged, unused_credit (unused time of the old plan, counted) and new_cost. Set `confirm: true`. Requires: token + balance for the prorated difference + confirm: true. No room on the server's host → 202 queued (paid, applied automatically, usually within 24 hours). Typical errors: 402 (top up), 409 upgrade_queued (one upgrade is already paid and waiting), 422 not an upgrade (pick from get_upgrade_options).

Start an isolated Firecracker microVM sandbox (ready in about 1 s; Linux with Python 3.12 + pip, Node.js 22 + npm, bash, git and curl; internet egress allowed so pip/npm install and git clone work; no inbound ports, SMTP blocked). `mode`: "ephemeral" (default — billed per second, minimum 60 s, auto-deleted after `idle_timeout` s of inactivity, default 300, max lifetime `ttl` up to 24 h) or "persistent" (billed per started hour, a month costs at most 730 h minus 25%; survives host maintenance; max `ttl` 30 days). `tariff` (default small): micro 0.25 vCPU/512 MB RAM/3 GB disk $0.0165/h · small 0.5 vCPU/1 GB RAM/5 GB disk $0.033/h · standard 1 vCPU/2 GB RAM/10 GB disk $0.066/h · plus 2 vCPU/4 GB RAM/15 GB disk $0.132/h · pro 4 vCPU/8 GB RAM/20 GB disk $0.264/h · max 8 vCPU/16 GB RAM/40 GB disk $0.528/h (pick plus or bigger for heavy pip installs such as torch, builds or data work). Headless browsers (Chromium via Playwright/Puppeteer) need `standard` or bigger — micro/small do not have enough RAM. If the host is busy the call fails with 503 capacity (Retry-After) — retry or choose a smaller tariff. Charged from the same prepaid balance as VPS (no subscription). Empty balance → 402 insufficient_balance (top up with topup_balance). If the balance runs out later, persistent sandboxes are paused (memory+disk snapshot, not billed) and resume automatically after a top-up; paused snapshots are deleted after 14 days. The response has `state: "running"` and `ready: true` once you can exec (usually immediately); if it says `starting`, call get_sandbox after 1-2 s. Always kill_sandbox when done. Requires: token + balance (a new account's first sandbox gets a free $1 trial credit once the account email is confirmed with a 6-digit code — 402 with trial=email_unverified until then: the human confirms it in the dashboard, or POST /auth/email/verification/send, then /confirm {code}; no top-up needed; until the first real top-up: micro or small, ephemeral, up to 2 at once, each deleted after 20 min (the $1 credit itself lasts 14 days) → 403 trial_tariff / trial_persistent, 429 trial_limit). Typical errors: 402 insufficient_balance → topup_balance; 503 capacity → retry or smaller tariff.

Execute a shell command (bash -lc) in a sandbox as root and return {exit_code, stdout, stderr, timed_out, truncated, duration_ms}. Shell operators are fine and never filtered: `apt-get update && pip install x | tee log; echo done > out`. If you call the server with raw HTTP/curl, the JSON body must be valid — escape double quotes inside `command` (\") or build the body with a JSON library; a broken body returns a JSON-RPC parse error (-32700), not a firewall block. Optional `cwd` (default /root) and `timeout` (default 30 s, max 55 per call). For commands longer than 55 s (builds, training, long downloads) set `background: true`: you get a `task_id` at once, then poll get_task for output and the exit code; kill_task stops it. Requires: token + live sandbox_id. Typical: timed_out after 55 s → repeat with background: true; 404 → sandbox expired, create a new one.

Delete a sandbox IMMEDIATELY and IRREVERSIBLY (running or paused): all files, installed packages, background tasks and memory are lost and cannot be recovered — download_file anything you need first. Billing stops; the final partial period is billed (ephemeral per second with the 60 s minimum, persistent per started hour). Requires: token.

Stop a running background task and all processes it started. Returns its final state (killed). The sandbox itself keeps running. Requires: token.

Order a VPS. `product` = plan slug from list_plans; `os_id` = an OS id from that plan's images. Optional `hostname` and `ssh_key` (public key — strongly recommended so you get key-based root login). Optional `location`: "de" (Germany) or "fi" (Finland) — omit it and we pick the location automatically. Orders are never refused for capacity: if the chosen country has no free room or IPv4 right now, the paid server waits in the creation queue in that same country (`get_vps_status` shows `queued: true`) and is created automatically, usually within 24 hours; the customer gets the usual access email. Optional `months` (1–36): the billing term paid upfront — the invoice is the monthly price × months, payment moves the paid-until date by exactly that many months, after that the server renews monthly from the balance; `months: 12` is the annual plan with its discount; terms other than 1 and 12 have no discount. Or `period` ("month" by default, or "year" for annual billing) or an explicit `plan_id` from list_plans `plans[]` (`months` takes precedence over both); an active automatic offer (`plans[].promo`) is applied to the first invoice and the response then carries `promo`. Windows plans (windows-*) accept only the Windows Server 2022 image, ignore `ssh_key`, and are reached over RDP as Administrator (see get_vps_status → access); the licence is BYOL. Branching on the response: • `paid_from_balance: true` → the prepaid balance covered it; the server is provisioning. Poll `get_vps_status` until status is `active` and the VM is reachable. • `paid_from_balance: false` → balance was insufficient; an unpaid `invoice` is returned. Call `pay_invoice` with `invoice.id` to get a crypto `checkout_url`, OR `topup_balance` then re-order. Several servers in one order: `quantity` 2–50 → one invoice, N separate services (each with its own renewal), names <hostname>-1…<hostname>-N, created one after another after payment (`service_ids` in the response). 50 is only a typo guard — there is no limit for new accounts and no maximum by free capacity: servers that do not fit right now are queued for creation (usually within 24 hours). Promo codes apply to single-server orders paid for 1 or 12 months only. Optional `addons`: "backups" (Managed Backups, monthly plans only — annual plans include them) and "extra_ipv4" (a second public IPv4, dedicated-IP plans only); each add-on is added to the same invoice for every month of the chosen term (the first month on an annual plan), see `get_order_limits` for availability and price. Send the same `idempotency_key` when you retry the same order — a repeated call returns the existing order instead of creating a second one. PROMO until 2026-10-31 23:59 Europe/Kyiv: -25% on ANNUAL billing, first year only, applied automatically (no code) to windows-medium ($171/yr), windows-small-ip ($252/yr) and windows-medium-ip ($324/yr); renewal at the regular annual price; windows-small not included — order with period="year". Requires: token + enough balance (else an unpaid invoice is returned). Never refused for capacity: no free room/IPv4 → the paid server is queued (get_vps_status queued: true, usually ready within 24 hours). Typical errors: 422 unknown product/os_id (see list_plans), 422 quantity above 50, 422 months outside 1–36, 422 coupon_term_only (promo code with a term other than 1 or 12 months).

Power-control a VPS: `start`, `stop` or `reboot`. Requires: token. Typical error: 409 during the first boot (setup still running) → wait and retry.

Exchange the CURRENT bearer token for a new one before it expires: returns `token` + `token_expires_at` (1 year by default, or `expires_in_days` 1-1825) and REVOKES the old token immediately. Inside this MCP session the new token is used automatically; with raw HTTP save it and stop using the old one. Every REST response carries the header X-Token-Expires-At; get_started shows the expiry and warns 30 days ahead. An already expired token cannot be refreshed — log in again (login) or create a token in the cabinet. Requires: a valid (not yet expired) token. The old token is revoked.

DESTRUCTIVE — all data is lost. REQUIRES confirm = exact hostname (from get_vps_status) or 'DELETE'. Agent must explicitly confirm with the human before calling. Wipes and reinstalls the VPS with the given OS image (`os_id` from list_plans). Provisioning runs asynchronously; poll `get_vps_status`. Requires: token + confirm (hostname or DELETE). Destroys all data.

Rotate the root password. The new password is applied to the LIVE VM immediately via the guest-agent (no reboot) and works within ~10-30s; the OLD password stops working. REQUIRES confirm = exact hostname (from get_vps_status) or 'DELETE'. Agent must confirm with the human before calling. Use this ONLY if the password was lost — NOT because SSH was not instant on a fresh order (a new VM needs ~60s to boot; poll get_vps_status, then reveal_password). New password is NOT in this response — read it ONCE via reveal_password; also emailed. Requires: token + confirm (hostname or DELETE). Only if the password is lost.

Revoke a delegation by its id (owner revokes access, or a delegate declines their own). The other side is notified. Use list_delegations / list_delegated_to_me to find the id. Requires: token.

Run a code snippet inside a sandbox and return {exit_code, stdout, stderr, timed_out, truncated, duration_ms}. `language`: python (Python 3.12), node (Node.js 22) or bash. Install packages first with exec_command (`pip install …` / `npm i …`). The code is passed to the interpreter on stdin, so it cannot read stdin itself. `timeout` seconds (default 30, max 55 per call). LONGER JOBS: set `background: true` — returns a `task_id` immediately (timeout then defaults to the sandbox's remaining lifetime); poll get_task with the returned offsets to read new output and the exit code, kill_task to stop it. The sandbox keeps billing while a task runs and is not idle-deleted. Output is capped at 1 MiB per stream for synchronous calls. Files and installed state persist between calls in the same sandbox. Requires: token + live sandbox_id. Typical: timed_out after 55 s → repeat with background: true.

Keep a VPS whose cancellation was scheduled with type end_of_period: the scheduled cancellation is removed, the server stays active and renews as usual. No money moves (end_of_period never refunds). An immediate cancellation cannot be undone — the VM is destroyed at once. get_vps_status shows `cancellation` {type, cancel_at, can_undo}. Requires: token + a scheduled end_of_period cancellation. Typical error: 409 nothing_to_undo.

Write a file into the sandbox at an absolute `path` (parent directories are created). Give `content` for UTF-8 text OR `content_base64` for binary. Limit 5 MB per file inline — for bigger files call `get_upload_url` and PUT the bytes to the link (no base64 through this chat). Optional `mode` like "755". Requires: token + live sandbox_id. Max 5 MB.

Initiate payment for an owned, unpaid invoice. Returns a PayRam `checkout_url`; the invoice settles (and the VPS provisions) automatically once the on-chain payment confirms. Requires: token. Pass invoice_id exactly as returned (a code like "2RUAWV4"). A human pays checkout_url.

Post a reply on one of your tickets. Use the ticket code from create_ticket / list_tickets. Requires: token.

Create a top-up invoice and return a `checkout_url` (PayRam crypto checkout). The balance is credited automatically once the on-chain payment confirms. `amount` is in account currency (USD); minimum and maximum are enforced server-side. Only one unpaid top-up may exist at a time. Requires: token. A HUMAN must pay checkout_url in crypto; the balance is credited automatically after confirmation.

Accept a delegation invitation using the `token` from the invite link. Requires being signed in as the invited email address: it grants operator access to your own account. No new token is returned — keep using yours. Requires: token of the invited email.

Close one of your tickets. `rating` (1-5) and `comment` are OPTIONAL — you can close without rating. Use the ticket code from create_ticket / list_tickets. Requires: token.

Open a support ticket with EQVPS. `subject` and `message` are required; optional `service_id` ties it to one of your VPS. The response includes the ticket `code` — use that with get_ticket / reply_ticket / close_ticket. Requires: token.

Grant OPERATOR access to one of YOUR VPS to another person by email (they can power/reinstall/console/hostname/rdns, but NOT renew, cancel or change billing). Sends them an invitation with an accept link. Optional `expires_days` for time-limited access. Owner-only. Requires: token (owner).

Get a short-lived HTTPS link (default 15 min, `ttl` 60-3600 s) that streams ONE file from the sandbox — e.g. a build artifact or archive up to 2 GB — without base64 in this conversation. Download it with `curl -fL -o <name> <url>` from wherever you work. The link only works while the sandbox runs and only for that path; treat it as a secret. Requires: token + live sandbox_id. The link expires (ttl) and dies with the sandbox.

Call this FIRST. Returns the whole flow in one response: the exact order of tools to rent a VPS and to run code in a sandbox (with example arguments), the only human step (paying a crypto checkout_url), auth rules (one account, reusable token), common errors with fixes, limits — and `you_are_here`: if you are authenticated, your balance, servers and the next call to make. Every other tool response also carries `next_steps`, and every error carries `error.fix` + `error.next`. Requires: nothing. Call this first.

Get a short-lived HTTPS link to PUT ONE file into the sandbox at `path` (up to 2 GB): `curl -fT <file> <url>`. One request carries at most 95 MB — for bigger files PUT parts in order with `?offset=<bytes already uploaded>` (each response returns `next_offset`; offset 0 overwrites). No base64 through this conversation. Requires: token + live sandbox_id. ≤95 MB per PUT; use ?offset for more.

Log in with email + password. Returns a bearer `token` (reusable until `token_expires_at`, 1 year by default or `token_ttl_days`; remembered for the rest of this MCP session). NOTE: accounts created via register_account have NO password by default — keep using the token from register instead. To be able to log in later, call `set_password` once while still authenticated with your register token. Requires: a password set earlier with set_password. Typical error: 401 invalid credentials (register_account accounts have no password until set_password).

Create a NEW EQVPS customer account (first_name, last_name, email). Use a real email address you control — reserved/test domains such as example.com are not suitable (no recovery, no notifications). Returns a bearer `token` that is reusable for every request until `token_expires_at` (1 year by default; optional `token_ttl_days` 1-1825) — it is NOT single-use; call `refresh_token` before it expires. Inside this MCP session the token is remembered automatically for the following tool calls. If you call the server with raw HTTP/curl instead, save the token to a file right away and send `Authorization: Bearer <token>` on EVERY request — a shell variable does not survive separate commands. Never call register_account again to "get a new token": that creates another, empty account. Optional backup: call `set_password` once, then `login` (email + password) returns a fresh token if this one is lost. Requires: nothing. Typical error: 422 email already registered → use login or your saved token instead of a new account.

Read the root (Windows: Administrator) password of a keyless VPS — shown ONCE. It is returned only after the VM has finished booting: at that moment the password is applied to the live VM, so it is guaranteed to work. While the VM is still booting the response carries `password_pending: true` and NO password — call again in ~30-60 s (the one-time reveal is NOT spent until a password is actually returned; no reset or reboot needed). After it has been shown once, later calls return no password: save it right away. Lost it? `reset_password` (needs confirm = hostname), then reveal_password again after ~20 s. If you ordered with an SSH key, you do not need a password — log in with the key. The response is the same server detail as get_vps_status plus the password. Requires: token + a keyless VPS. Typical: password_pending=true while the VM boots — not an error, call again in 30-60 s; no password after it was shown once → reset_password.

Public: sandbox tariffs — micro 0.25 vCPU/512 MB RAM/3 GB disk · small 0.5 vCPU/1 GB RAM/5 GB disk · standard 1 vCPU/2 GB RAM/10 GB disk · plus 2 vCPU/4 GB RAM/15 GB disk · pro 4 vCPU/8 GB RAM/20 GB disk · max 8 vCPU/16 GB RAM/40 GB disk — with per-second/hour/month prices, the billing model and limits (synchronous exec up to 55 s, background tasks longer; files up to 5 MB per transfer; runtimes: Python 3.12 + pip, Node.js 22 + npm, bash, git, curl). No authentication needed. Writing code instead of calling MCP? Official SDKs on the same REST API and token: Python `pip install eqvps`, TypeScript/JavaScript `npm i @eqvps/sdk` (docs: https://eqvps.com/en/docs/sandboxes). Requires: nothing.

Set the VPS hostname (valid DNS name). Applied immediately inside the running server via the guest agent (Linux: hostnamectl + the 127.0.1.1 line in /etc/hosts; Windows: renamed, takes effect after a reboot — the response then has `reboot_required: true`). The server must be running with its guest agent active; otherwise the call fails with 409 `agent_unavailable` and nothing is changed. Your password, SSH host keys and files are not touched. Requires: token, server running. Typical error: 409 agent_unavailable → start the server / wait for boot.

Set a password for THIS account (the one your bearer token belongs to). Accounts from register_account have no password by default — the bearer token is the credential. Call this ONCE to enable email+password `login` as a recovery method in case the token is lost. Needs only the new password (min 8 chars, letters+numbers) — no current password the first time. If a password was already set, this returns 409 (use change-password instead). Requires: token. Typical error: 409 password already set → use login.

Read a SMALL file from the sandbox (absolute `path`, max 5 MB) into this conversation: `content` as UTF-8 text by default, `as_text: false` → `content_base64`. For build artifacts, archives, binaries or anything big use `get_download_url` instead — you get a short-lived link and download it with curl, without pulling base64 into your context. Requires: token + live sandbox_id. Max 5 MB — bigger: get_download_url.

Return the account's prepaid credit balance and currency. `order_vps` spends from this balance automatically when it is sufficient. Requires: token.

Before order_vps: the per-order maximum (`max_quantity` = 50, a typo guard; `limit_reason` max_per_order) and which add-ons a plan has with their monthly price (`addons.backups`, `addons.extra_ipv4`). Orders are never refused for capacity — servers without free room are queued for creation (usually within 24 hours, see `queue_note`). Pass the same `product` and `months` (or `period`/`plan_id`) you will order; the response carries `months`, `term_price` (plan price for the term, one server, before add-ons and an automatic offer) and `terms` (1–36 months, quick picks 1/3/6/12). Works without a token. Requires: nothing (with a token the limit is for your account; without one — as for a new account).

Status of one sandbox (state running/paused, mode, tariff, expires_at; paused ones show pause_reason and delete_after) plus usage: running seconds, CPU seconds actually used, egress bytes, price per hour, amount already billed and the estimated total so far. Requires: token.

Status and NEW output of a background task: `state` (running | done | failed | killed | timeout), `exit_code`, and the stdout/stderr text produced since the offsets you pass. Start with offsets 0, then pass `stdout_next_offset` / `stderr_next_offset` from the previous response to get only new output. `done: true` means finished. Poll every few seconds; each call is quick. Up to 8 MiB per stream is retained (older output is dropped and reported in `*_dropped`). Requires: token.

Read one ticket and its full message thread. Each message has an `author`: `you` or `staff` — a `staff` message is a reply from support. Poll this to see new answers. The ticket code comes from create_ticket / list_tickets. Requires: token.

List the plans this VPS can switch to IN PLACE with its data kept: bigger plans of the same network type (resize: more vCPU/RAM/disk), NAT → dedicated IPv4 (convert: adds a public IP) or dedicated → the equivalent NAT plan (convert_to_nat: drops the IP, the unused price difference is refunded to the balance). Each option: product_id, name, monthly, prorated_topup (charged now for the rest of the current period), mode. Shrinking vCPU/RAM/disk is not possible (a disk cannot be reduced). The server must be active. Options come grouped by `line` (same = a bigger plan on the same network, to_ip, to_nat). Every option can be ordered; `capacity_now: false` (with `wait_reason` capacity | no_ip) means the server's host has no free room or IPv4 for it right now — change_plan then charges as usual and the upgrade is applied automatically from the queue, usually within 24 hours (the server is never moved to another host). `pending_upgrade` is set (and `options` empty) when an upgrade is already paid and waiting. `unused_credit` is the value of the unused time on the current plan, `new_cost` the new plan for the same time; prorated_topup = new_cost − unused_credit, which is what change_plan charges. Requires: token, server active.

Time-series resource metrics (CPU %, memory, network, disk) for a VPS. `timeframe` ∈ hour|day|week|month (default hour). Requires: token.

Get full detail for one VPS: status, specs, live VM state/uptime, and access info (host, port, ready-to-paste `command`; `access.method` = ssh for Linux, rdp for Windows — port follows the plan: dedicated IP 22/3389, NAT 20000+vmid). READ-ONLY since 1.9.1: it never reveals or changes anything, so it is safe to poll. ROOT PASSWORD (keyless VPS): `password_available: true` means a password is waiting — read it ONCE with `reveal_password` (the old `reveal: true` argument is still accepted but only points you there). If you supplied an SSH key at order time, log in with that key (no password); `access.ssh_ready` (Linux) / `access.rdp_ready` (Windows) is a LIVE probe of the login port: on a fresh order the first boot applies OS updates, so SSH usually opens 1-5 minutes after the VM is running. While it is false the ready-to-paste `command` is withheld and `ready_note` + `retry_after_seconds` tell you to poll again — do not reset, reboot or reinstall during that window. Use `reset_password` ONLY if the password is lost. Poll this after `order_vps` to watch provisioning reach `active`. NAT plans (no dedicated IP): the SSH `port` shown is an EXTERNAL DNAT port forwarded to the VM internal port 22 (`internal_port` in the response). If you configure a host firewall, allow the INTERNAL port — `ufw allow OpenSSH` — NOT the external port, or `ufw enable` will lock SSH out. See `firewall_note` in the response. Requires: token. Typical: access.ssh_ready=false right after an order — not an error, poll again after retry_after_seconds.

List services other owners have delegated operator access to you — the VPS you can operate but don't own. Requires: token.

List outgoing delegations you (the owner) have granted on your services — who has operator access to what, and its status. Requires: token.

List all available VPS plans (catalog) with pricing, specs and the OS images each plan can boot: Linux plans (NAT or dedicated IPv4, from $3/mo) and Windows Server 2022 plans (slug windows-*, BYOL — the customer activates their own licence; RDP access, 150 Mbit/s port, from $11/mo). No authentication needed. Use this first to pick a `product` slug and an `os_id` for `order_vps`. Each plan lists `plans[]` (monthly and annual `plan_id`); an active automatic offer shows up as `plans[].promo` and in `meta.promotions`. PROMO until 2026-10-31 23:59 Europe/Kyiv: -25% on ANNUAL billing, first year only, applied automatically (no code) to windows-medium ($171/yr), windows-small-ip ($252/yr) and windows-medium-ip ($324/yr); renewal at the regular annual price; windows-small not included — order with period="year". Requires: nothing.

List the account's sandboxes (running and paused) with mode, tariff, state and expiry. Requires: token.

List your support tickets with status and last-message info. `last_message_author: "staff"` means support has replied since you last looked. Requires: token.

List the account's ACTIVE VPS services — active, provisioning, and suspended servers (deleted/cancelled are excluded). Use the `id` as `service_id` for the management tools. If a server is missing from this list it has been deleted — do not query its status or try to manage it. Requires: token.

Return the authenticated account profile (id, name, email). Use to verify the bearer token is valid. Requires: token.