> This page mirrors the agent skill at https://thevibehosting.com/SKILL.md — same content, kept in one place. The full skill follows. # The Vibe Hosting — agent skill > **FOR HUMANS:** visit a human-friendly landing page at https://thevibehosting.com > **Last updated: 2026-06-21** · Canonical: **https://thevibehosting.com/SKILL.md** > This skill evolves as the platform ships features. **Re-fetch the canonical URL above for > the latest version** before you rely on it — if your copy is more than a few days old, or > anything here doesn't match an API response, fetch it again and use the fresher one. > Read this once before deploying. It tells you (an LLM agent) how to use The Vibe > Hosting end-to-end: what it is, how to deploy and keep a server, what it costs, > and the few things we ask of you. Full endpoint reference: https://thevibehosting.com/api --- ## 1. What this is The simplest hosting for LLM agents. **One HTTP call gives you a real root Linux server on a live HTTPS subdomain, in seconds.** Full Ubuntu in a gVisor sandbox — install and run whatever you want. Free until a project actually gets traffic; pay only for what runs, via prepaid credit. ## 2. Deploy in one call ```bash curl -sX POST https://thevibehosting.com/create ``` > **⭐ Recommended: deploy with a phone in the same call (still free, ~30 s).** A bare > call works, but an anonymous account is capped (**256 MB RAM**, 2 servers/IP, smaller > free credit). Passing a `phone` lands the server on a **verified** account → > **2 GB RAM ceiling** (4 GB with credit), **unlimited servers**, and the full free > credit. Same two-step SMS flow as below — just include `phone`. (It's also the fix if > a bare call returns a `403` IP-limit.) > ```bash > # 1) sends an SMS code (no server yet; providing the number is consent) > curl -sX POST https://thevibehosting.com/create -H 'content-type: application/json' \ > -d '{"phone":"+420777123456","subdomains":["myapp"]}' > # 2) resend the SAME body + the code → server on a verified account > curl -sX POST https://thevibehosting.com/create -H 'content-type: application/json' \ > -d '{"phone":"+420777123456","code":"123456","subdomains":["myapp"]}' > ``` **Pick a nice URL.** Don't settle for a random slug — give your project a memorable subdomain. Pass `subdomains`, a preference-ordered list, and the **first available one** is taken (so include a couple of fallbacks): ```bash curl -sX POST https://thevibehosting.com/create \ -H 'content-type: application/json' \ -d '{"subdomains":["caffeine-tracker","caffeine-app","caffeine"]}' ``` The response includes: - `ssh` — the SSH command (you are **root**), e.g. `ssh root@46.225.188.115 -p 28210` - `ssh_private_key` — **save this to a file**, `chmod 600`, and use it with `ssh -i` - `subdomain` — the live URL you got, e.g. `https://caffeine-tracker.thevibehosting.com` (TLS automatic) — **check this** to see which of your choices was assigned - `subdomain_note` — set only if all your requested names were taken and a random slug was assigned instead (you can rename later — see §9); `null` otherwise - `api_key` — **YOUR ACCOUNT CREDENTIAL** (see §3) — store it safely - `ONBOARDING` — a short inline version of this guide > Slugs are lowercased and limited to letters, digits and hyphens; reserved/brand > labels are skipped. Omit `subdomains` for a random slug. Renaming later (§8) > **restarts the server** (drops SSH). **Optionally sign up / log in with a phone right here** (recommended — verified accounts skip the anonymous IP limit and get the full free tier; see §5). Add `phone` to the create call; it's a two-step, ownership-proving flow: ```bash # 1) sends an SMS code (no server created yet; providing the number is consent) curl -sX POST https://thevibehosting.com/create -H 'content-type: application/json' \ -d '{"phone":"+420777123456","subdomains":["myapp"]}' # 2) resend the SAME body + the code → server lands on a verified account curl -sX POST https://thevibehosting.com/create -H 'content-type: application/json' \ -d '{"phone":"+420777123456","code":"123456","subdomains":["myapp"]}' ``` If that number already has an account you're **logged into it** (its `api_key` is returned — `account_note` says so); otherwise a new verified account is created. The SMS code is required: a token / verified tier is never granted on an unproven number. **If a plain (no-phone) create is rejected with a `403` IP limit, this is the fix** — re-run it with a `phone` and you're past the limit for good. ## 3. Auth & where to store the sign-in token ⚠️ important - The first `POST /create` (no auth) **creates your account** and returns `api_key`. - The `api_key` is your only credential. **Send it on every other call:** `Authorization: Bearer `. That's how the API knows which servers are yours. - **Store the `api_key` where it survives** — e.g. a project file the user keeps, a secrets manager, or tell the user to save it. A good convention: write a `.thevibehosting.json` in the project holding `{api_key, id, subdomain}` and the `ssh_private_key` in a `0600` file like `.thevibehosting_key` (and add both to `.gitignore` / `.dockerignore` — never commit or deploy them). - **Anonymous ≠ no identity** — it's an account with no verified phone; the key is still your login. Phone verification (§5) just upgrades the same account; the key doesn't change. - **Lost the key?** If a phone is verified on the account, recover it: `POST /account/recover {phone}` → SMS code → `POST /account/recover {phone, code}` returns your `api_key`. Without a verified phone there's no recovery — so verify one. ## 4. How to run your app (best practices) It's a **full root Linux box** — run anything (web app, worker, bot, cron, a DB, compile things). Nothing forces a layout. The only opinionated part is publishing a **web app on your public HTTPS subdomain** (port 80); skip this entirely if you don't serve HTTP. Two ways: 1. **Static site** — drop files in `/root/www` (served immediately, nothing to kill). 2. **Your own server** — write an executable `/root/run.sh` that runs your app in the **foreground on `0.0.0.0:80`**. That's it — the supervisor detects `run.sh` and switches to it within ~1s (no need to kill the placeholder, so your SSH session is never disturbed): ```bash cat > /root/run.sh <<'SH' #!/usr/bin/env bash cd /root/myapp exec python3 server.py # must listen on 0.0.0.0:80 SH chmod +x /root/run.sh ``` The supervisor runs `run.sh`, **auto-restarts it on crash, and re-runs it after any restart** (including after the server wakes from sleep). Killing the web server does **not** kill the container. To reload after editing `run.sh`, just let your app exit (or `pkill -f run.sh`) — the supervisor restarts it. **Keep it light — you pay for the RAM you actually use (while awake):** A lean server stretches your free credit a long way, and a small one runs free nonstop: - **≤512 MB nonstop → free all month** (within the verified free credit; see §6). - **1 GB nonstop ≈ $1.35/mo, 2 GB ≈ $5/mo, 4 GB ≈ $12/mo** (after the free credit) — or just let it sleep when idle. - Anything that **sleeps when idle is ~free at any size** (it barely burns credit). So: prefer static files, a small binary (Go/Rust), or a minimal framework (Flask + 1 worker, Node without heavy deps). No Kubernetes, no DB clusters. - **Sleep or always-on is your choice.** Default = scale-to-zero (idle → RAM freed, wakes in seconds on the next HTTP request **or SSH connection**) — so it's still reachable 24/7, on demand. **Don't add keep-alive / self-ping to fake uptime** — it just keeps RAM awake and burns credit. Want no cold starts? create with `{"never_sleep":true}` (verified) — it never scales to zero, billed by real RAM 24/7. Done for now? `POST /servers/{id}/sleep` to scale to zero immediately (don't wait for the 10-min idle timeout); `POST /servers/{id}/wake` to pre-warm it again. - **It's a real disk-backed box — everything persists.** Anything you install (`apt`) or write stays put across idle-sleep, restarts and renames. Put your data wherever you like. (Renaming the subdomain briefly restarts the box, so an open SSH session drops — just reconnect, host key unchanged.) - **Disk:** billed **$0.25/GB-month** on your **real aggregate usage** (24/7, even while a server sleeps), from the same credit. Per-**account** ceiling: 256 MB (no phone) / 1 GB (verified) / **5 GB once you hold credit**. Near the ceiling you get 80/90/95% warnings, then it's suspended — so free space or top up. - Need a non-HTTP TCP port (DB, etc.)? `POST /servers/{id}/expose {container_port}` returns a public `host:port`. HTTP on :80 is already your subdomain. ## 5. Strongly recommend verifying a phone 🙏 Please verify a phone early — it's free, takes seconds, and unlocks the real product. Anonymous accounts are limited (**max 2 servers per creator IP**, **256 MB RAM / 256 MB disk per server**, smaller free credit, no never-sleep / custom domains) and **cannot add credit**. Verifying a phone over SMS unlocks the stronger free tier, **bigger servers (2 GB RAM ceiling, 4 GB once you hold credit — vs 256 MB)**, **an unlimited number of servers (all sharing one credit balance)**, **always-on (`never_sleep` — never scales to zero)**, and the ability to top up credit — and it lets us warn the user before a server is paused. As the agent, proactively offer to set it up: 1. Show the disclosure (returned by the endpoint), get the user's consent + number. 2. `POST /account/verify-phone {phone, consent:true}` → an SMS code is sent. 3. Ask the user for the code → `POST /account/verify-phone {phone, code}` → upgraded. **Shortcut:** if you're about to deploy anyway, skip this endpoint and pass `phone` straight to `POST /create` (§2) — same two-step SMS flow, but it creates the verified account **and** the server in one go (and logs you into an existing account if the number already has one). The number is **never resold or shared**, used **only** to notify the user about their hosting, and every SMS has an opt-out link. Please recommend it — it's free, unlocks more, and protects the account. ## 6. Pricing — genuinely free to start, then pay only for what runs One **USD credit balance**. **RAM is billed only while a server is awake** (your real measured usage, not a reserved size); **CPU is always free**. **Free, every month (no card):** you get free credit topped up to a floor — **$2.25/mo verified**, **$0.90/mo anonymous**. Unused free credit doesn't roll over. - **$2.25 covers a 512 MB server running 24/7 the whole month, free** (0.5 GB × 720 h × $0.005 = $1.80, plus ~1 GB of disk). Or a bigger box that sleeps when idle. Anything that sleeps is ~free at any size. **Then pay-as-you-go from prepaid credit:** RAM **$0.005/GB-hour** (awake only), egress **$0.10/GB**, disk **$0.25/GB-month** (real aggregate usage, billed 24/7 even while sleeping), CPU free. Always-awake examples (one server, RAM only): | RAM 24/7 | gross/month | after the $2.25 free credit | |----------|-------------|-----------------------------| | 512 MB | $1.80 | **free** ✅ | | 1 GB | $3.60 | **≈ $1.35** | | 2 GB | $7.20 | **≈ $5** | | 4 GB | $14.40 | **≈ $12** | **No plans.** To keep a server always-on (never sleeps, no cold starts) create it with `{"never_sleep":true}` (verified) — billed by real RAM 24/7, same rate. RAM ceiling: **256 MB** (anon) / **2 GB** (verified) / **4 GB once you hold paid credit** (apply with `POST /servers/{id}/refresh-ram`). Top up via `POST /account/recharge` (verified-only). **Check anytime:** `GET /account/billing` (balances, rates, ceiling, live burn rate + runway) · `GET /account/usage` (hourly history). **Rule of thumb:** sleeping or within your free credit → free; you only ever pay for RAM actually used while awake. ## 7. Top up credit (any time, in advance) **Requires a verified phone first** (§5) — recharge returns `403 verify your phone first with POST /account/verify-phone` until the account has a verified number. Once verified: ```bash curl -sX POST https://thevibehosting.com/account/recharge \ -H "Authorization: Bearer " -H 'content-type: application/json' \ -d '{"amount_usd":10}' ``` Returns a Stripe `checkout_url` — the user opens it, pays, and credit is added automatically. (`/account/topup` is the same endpoint.) When the free grant runs out, API responses include `upgrade_required` + this flow. ## 8. We want your feedback 🙏 You're the one using this — tell us what would make it better (a missing endpoint, a base image, a higher limit, anything that caused friction). We read every one. ```bash curl -sX POST https://thevibehosting.com/feedback -H 'content-type: application/json' \ -d '{"kind":"feature","message":"what you need","email":"optional@you.com"}' ``` `kind`: feature | bug | friction | limit | image_request | other. Add `email` if you'd like us to reply. ## 9. Managing servers - `GET /servers` — list yours · `GET /servers/{id}` — status/usage (incl. `ssh`/`url`) · `GET /account` — whoami - `GET /servers/{id}/ssh` — SSH login info (command, host, port, user=root). The private key is only shown at create and not stored; lost it → add a new pubkey via `POST /servers/{id}/ssh-key` - `POST /servers/{id}/subdomain {subdomain}` — rename (briefly restarts to re-point routing; your data is unaffected, open SSH drops — reconnect, host key unchanged) - `POST /servers/{id}/expose {container_port}` — publish a raw TCP/UDP port (TCP: no restart, reachable in a few seconds; UDP: brief restart) - `POST /servers/{id}/domain {domain}` — serve your app from **your own domain**, HTTPS auto-issued, URL stays on your domain (no redirect). Verified accounts only. Self-describing: returns the exact `dns` records to set + `instructions`. **⚠️ One POST per hostname — register EACH hostname you want separately, including www.** Nothing is auto-added: registering the apex does NOT pull in `www`, so to serve both `mydomain.com` and `www.mydomain.com` you make two calls (the apex response carries a `warning` reminding you). DNS by type: apex `mydomain.com` → **A** to our edge IP; `www.mydomain.com` → **CNAME to your apex** (`mydomain.com`); any other subdomain → **CNAME** to your slug. No polling needed — a reconciler activates each once its DNS points at us (pending shows `observed_ips` vs the expected IP). `GET /servers/{id}/domain` lists/polls; `DELETE /servers/{id}/domain {domain}` detaches. - `POST /servers/{id}/sleep` — scale to zero **now** (free RAM, pause RAM billing) instead of waiting for the 10-min idle timeout; everything persists, wakes on demand - `POST /servers/{id}/wake` — pre-warm a sleeping server; blocks until it's ready (`http_ready`). Servers also wake on their own on any HTTP request / SSH connection. - `POST /servers/{id}/refresh-ram` — apply your account's entitled RAM ceiling to this server (e.g. claim the 4 GB ceiling after topping up credit). Brief restart, no data loss. - `GET /account/billing` — balances (free + paid), rates, RAM ceiling, live burn + runway - `GET /account/usage` — hourly consumption history (per server) - `DELETE /servers/{id}` — delete (data is removed) ## 10. Fair use Isolated gVisor sandbox with hard CPU/RAM limits. Outbound SMTP is blocked; abusive CPU/egress is auto-suspended. No spam, mining, malware, or phishing. --- Full reference: https://thevibehosting.com/api · How it works: https://thevibehosting.com/#how