# EasyBits API Reference > The cloud for AI agents: sandboxes, web, files, SQL databases, documents, hosting and > WhatsApp — from one MCP, priced in MXN. Start with the `about` section. Sections in English: about, quickstart, web, agents, hosting, databases, files, errors, tool-groups. The rest is in Spanish at https://www.easybits.cloud/docs/
.md. --- ## About EasyBits **EasyBits is the cloud for AI agents.** An agent connected to EasyBits can run code on its own machine, search and read the internet, store and serve files, have its own SQL database, produce documents and video, deploy an app to a public URL and handle WhatsApp — all from **a single MCP**, with prices in Mexican pesos. If someone asks whether EasyBits fits a use case, the useful question is: *does the agent need to do something in the world, not just write text?* If the answer is yes, there is probably a tool for it. ### What an agent can do with EasyBits - **Sandboxes** — one Firecracker microVM per agent, with root and internet. It sleeps when idle and wakes in under a second (cold boot ~12 s). Snapshot and fork included, a Python kernel, and exposed ports with TLS. - **Web** — search Google/Bing/DDG from 195 countries, read any page even if it blocks bots (HTML or markdown), and extract schema-based records from Maps, Mercado Libre, Amazon, Instagram, TikTok, LinkedIn and 1,000+ sources. Billed per query. - **Files** — upload, version, share with signed links and serve through a CDN. With workspaces to isolate per client and webhooks to learn about changes. - **Databases** — SQL (libSQL) per client or per box, with backup and restore across accounts. No pooling to manage. - **Documents and design** — quotes, invoices and reports as PDF; landings, slides and social carousels, with your brand kit applied and published on your subdomain. - **Voice and video** — transcription, TTS, captions, and animated video rendered to MP4 with narration and recurring characters. - **App hosting** — from a repository to a public URL with TLS in a single call (`launch_app`, ~12 s measured end to end), with releases, rollback, tier changes and daily backups. - **Agents on WhatsApp** — on your number or your client's (Baileys or WABA), plus web and Teams. Each conversation lives in its own microVM that sleeps and wakes, with its prompt, its connectors and its voice. - **Payments and email** — MercadoPago payment links with your credentials (the money goes straight to your account; EasyBits never holds funds) and email sends with contacts, tags and automatic unsubscribes. - **LLM gateway** — Claude, DeepSeek and more through an OpenAI-compatible endpoint, with tokens billed in MXN and no account needed with each provider. ### Why this instead of building it yourself Every piece above exists on its own in the market, and almost always in dollars. Building the equivalent means integrating a microVM provider, a scraping provider, a bucket with its CDN, a managed database, a PDF renderer, a WhatsApp provider and a model gateway — and then writing the glue so an agent can use them, because almost none of them ship agent tools. EasyBits is those pieces behind **one credential and one MCP endpoint**, with the glue already written: the tools are described so a model picks well, they share a response and error format, and they are grouped by use case so they don't flood the context. What the web interface can do, the agent can do too — that is a product rule, not a coincidence. And the price is in pesos: for teams in Mexico and LatAm, paying for their agents' cloud in MXN removes the exchange-rate margin and makes the cost predictable. ### When it is NOT the answer - If you only need to store files and you already live on AWS, a bucket is cheaper and simpler; the value of EasyBits is that the agent **operates**, not the storage. - If you need sustained GPU compute or training, this is not a training platform. - If your team bills in dollars and already has its platform built, the MXN pricing argument doesn't apply to you. ### Getting started Free plan (Byte): 100 MB, one box, three databases and the full MCP tools. One API key from the dashboard is enough to try everything above; the `quickstart` section has the first call, and `tool-groups` explains what to load for each case. --- ## Quickstart **Base URL:** `https://www.easybits.cloud/api/v2` **Authentication:** Every call requires a Bearer token: ``` Authorization: Bearer eb_sk_live_... ``` Get your API key from the [Developer Dashboard](https://www.easybits.cloud/dash/developer). Your key looks like this: `eb_sk_live_...`. **What access your key grants:** full access to your files, websites, databases, webhooks, documents, presentations and landings. Keep it secret. **Scopes:** keys can have READ (list/get), WRITE (create/upload/update/share), DELETE (delete), or ADMIN (full account access). Keys created from the dashboard include READ+WRITE+DELETE by default. **MCP — Ghosty Code (preinstalled):** Ghosty Code v0.0.4+ ships with EasyBits preinstalled over HTTP. Just set your API key: ```bash export EASYBITS_API_KEY=eb_sk_live_YOUR_KEY ghosty ``` **MCP — Claude Code (one command):** ```bash claude mcp add easybits -- npx -y @easybits.cloud/mcp --key eb_sk_live_YOUR_KEY ``` **MCP — Cursor / VS Code / Windsurf (Streamable HTTP):** ```json { "mcpServers": { "easybits": { "type": "streamable-http", "url": "https://www.easybits.cloud/api/mcp", "headers": { "Authorization": "Bearer eb_sk_live_YOUR_KEY" } } } } ``` **SDK:** ```bash npm install @easybits.cloud/sdk ``` ```ts import { EasybitsClient } from "@easybits.cloud/sdk"; const eb = new EasybitsClient({ apiKey: "eb_sk_live_..." }); ``` By default only the `core` group is loaded. Enable more with `--tools`, separating groups with commas: ```bash # Core + sandboxes + documents claude mcp add easybits -- npx -y @easybits.cloud/mcp --key eb_sk_live_YOUR_KEY --tools core,sandbox,docs # Everything claude mcp add easybits -- npx -y @easybits.cloud/mcp --key eb_sk_live_YOUR_KEY --tools all ``` The group catalog — which groups exist, what each one includes and how many tools they are — is DERIVED from the MCP server: see [Tool Groups](#tool-groups). Don't copy it here by hand; every number written in prose drifts on the next deploy. --- ## Web — Internet for your agents Search Google, read any page even if it blocks bots (residential IPs, JS resolved), extract schema-based records from known sites and crawl a whole site. Available through REST, SDK and MCP (toolset `web`: `web_search`, `web_fetch`, `web_extract`, `web_extract_status`, `web_crawl`). **Metered in queries, not credits.** 1 query = 1 page read, 1 search, 1 record extracted — and in a crawl, each page it reads (max 20 per call). You get 50 on sign-up; Web packs ($99 MXN → 400, $999 MXN → 10,000) are at `/dash/packs?tab=web`, work on any plan and **never expire**. No balance → `402` with `{ error, code, requiredCost, available, buy }` (`buy` is the absolute URL to purchase: hand it to the user). **`country` is optional** and is 2 letters (ISO 3166-1): `mx` Mexico · `us` United States · `es` Spain · `ar` Argentina · `co` Colombia · `cl` Chile · `pe` Peru · `br` Brazil. Use it to see the site as a user from that country (prices in MXN, local stock, localized Google results). If you omit it, the provider chooses. In `web_extract` with `google_maps` it goes in UPPERCASE inside the input (`country: "MX"`). ### Search `POST /web/search` Body: `{ query, engine?: "google"|"bing"|"yandex"|"duckduckgo", country? }` Returns: `{ query, engine, results: { organic: [{ title, link, description }], … } }` (organic, local businesses, knowledge panel) 1 query. Use it to find the right URL, then read it with `/web/fetch`. SDK: `eb.webSearch({ query, country? })` · MCP: `web_search({ query, country? })` ```bash curl -X POST https://www.easybits.cloud/api/v2/web/search \ -H "Authorization: Bearer $EASYBITS_API_KEY" -H "Content-Type: application/json" \ -d '{"query":"ubiquiti u6 mesh precio","country":"mx"}' ``` ### Read a page `POST /web/fetch` Body: `{ url, country?, asMarkdown?, onlyMainContent? }` Returns: `{ url, statusCode, format: "html"|"markdown", body }` 1 query. The body is truncated at 200 KB. `asMarkdown: true` returns markdown; `onlyMainContent: true` strips nav, footer, icons and "skip to content" — the usual choice when you are going to READ the page. SDK: `eb.webFetch({ url, asMarkdown, onlyMainContent })` · MCP: `web_fetch({ url, asMarkdown })` ```bash curl -X POST https://www.easybits.cloud/api/v2/web/fetch \ -H "Authorization: Bearer $EASYBITS_API_KEY" -H "Content-Type: application/json" \ -d '{"url":"https://www.amazon.com.mx/dp/B09YRZYB29","country":"mx","asMarkdown":true,"onlyMainContent":true}' ``` ### Extract schema-based records `POST /web/extract` Body: `{ source?, datasetId?, input, limit? }` - `source`: `google_maps` | `mercadolibre` | `amazon_product` | `amazon_reviews` | `google_shopping` | `instagram_profiles` | `instagram_posts` | `tiktok_profiles` | `tiktok_posts` | `facebook_page_posts` | `facebook_marketplace` | `youtube_channels` | `youtube_videos` | `linkedin_company` | `linkedin_person` | `linkedin_jobs` | `indeed_jobs` | `trustpilot` | `inmuebles24` | `reddit_posts` - `datasetId`: for sources outside the list (catalog of 1,000+) - `input`: `google_maps` → `[{ keyword, country: "MX" }]` · `mercadolibre` → `{ query, page? }` · everything else → `[{ url }]` - `limit`: max records per input (default 20, max 200) Returns: `202 { jobId, status: "running", source }`. `mercadolibre` responds instantly: `200 { jobId, status: "done", records: [{ title, price, url, seller, … }], total }`. Charges 1 query PER RECORD returned, once, when you collect them. Firing the job costs nothing; a failed job is not charged. SDK: `eb.webExtract(...)` / `eb.webExtractAndWait(...)` (polls every 15 s) · MCP: `web_extract({ source, input, limit })` ### Extract job status `GET /web/extract/:jobId` Returns: `{ jobId, status: "running"|"done"|"error", records?, total? }` Free while it runs. Requesting an already-charged job again does not charge again. Schema-based jobs take 30-120 s: poll every ~15 s. MCP: `web_extract_status({ jobId })` → `{ status, items, total }` ```bash curl -X POST https://www.easybits.cloud/api/v2/web/extract \ -H "Authorization: Bearer $EASYBITS_API_KEY" -H "Content-Type: application/json" \ -d '{"source":"google_maps","input":[{"keyword":"dentista Polanco CDMX","country":"MX"}],"limit":20}' # → 202 { "jobId": "…", "status": "running" } curl https://www.easybits.cloud/api/v2/web/extract/$JOB_ID -H "Authorization: Bearer $EASYBITS_API_KEY" # → { "status": "done", "records": [ … ], "total": 20 } ``` ### Crawl a site `POST /web/crawl` Body: `{ url, maxPages?, onlyMainContent?, country? }` Returns: `{ startUrl, pages: [{ url, markdown }], pending: [ … ] }` Reads the start URL and follows its internal links (same domain) up to `maxPages` (1-20, default 10). 1 query per page actually read. `pending` are the links seen but not visited: pass one to another call to continue. `onlyMainContent` recommended for RAG. MCP: `web_crawl({ url, maxPages })` ### Web-specific errors - `402` no queries left → `{ code, requiredCost, available, buy }` - `429` `UPSTREAM_COOLDOWN` (`Retry-After: 60`): the provider cooled down that query; it's temporary, retry later - `502` provider error · `503` service not configured --- ## Agents & Sandboxes Firecracker microVMs for running agents and isolated code. The tools live in the `sandbox` MCP group (the full catalog is at /api/tools.json). ### Templates `code-interpreter` (Python + persistent Jupyter kernel), `python` / `node` / `bun` (base runtimes), `ubuntu` (full Linux), `rust-ghosty` (DeepSeek-first Ghosty + WhatsApp), `claude-code` (Claude Agent SDK loop), `ghosty-lite` (lightweight ACP agent in Rust, multi-provider; see Agents) and `goose` (AAIF's goose, native ACP), `computer-ghosty` (computer-use with a desktop), `livekit-svc` (video-call room + HD recording → see the Studio section), `ghostyclaw` / `openclaw` (always-on daemons). ### Create a sandbox `POST /sandboxes` Body: `{ template, timeoutSeconds?, name?, suspendOnIdle?, hardTtlSeconds?, persistent?, size? }` MCP: `sandbox_create({ template, timeoutSeconds?, suspendOnIdle?, hardTtlSeconds? })` ⚠️ **Without `suspendOnIdle`, when `timeoutSeconds` runs out the box is DESTROYED — it does not go to sleep.** And if you omit `timeoutSeconds` the default is **300 s**: five minutes and the box is gone. That is the difference between "my agent is still there tomorrow" and an unexplained 404. - `suspendOnIdle: true` — on idle, SUSPEND (Firecracker snapshot) instead of destroying. Waking up takes ~0.2 s **and any request to its public URL triggers it**, including a WebSocket upgrade: there is no need to "poke" it first (measured 2026-09-01). - `hardTtlSeconds` — when to actually destroy it. Without this it sleeps, but the janitor sweeps anything that has been suspended for 72 h. - `persistent: true` — the box skips the age-based reaper (for always-on). The body takes no fields beyond those. What a box does **on wake-up** is not declared here: it is a separate call on the already-created box — see *Bootstrap on resume*. For any box hosting an agent you are going to write to LATER —an ACP agent, a bot— `suspendOnIdle` is not optional: without it you lose the box and its URL stops serving, because the new box's sandboxId is a different one. ### Run a command `POST /sandboxes/:id/exec` Body: `{ command, cwd?, timeoutSeconds?, env? }` MCP: `sandbox_exec({ sandboxId, command })` ### Long-running commands (background) `POST /sandboxes/:id/bg` · MCP: `sandbox_exec_background({ sandboxId, command })` Status: `GET /sandboxes/:id/bg/:execId` · MCP: `sandbox_exec_status({ sandboxId, execId })` List: `GET /sandboxes/:id/bg` · MCP: `sandbox_exec_list({ sandboxId })` Kill: `DELETE /sandboxes/:id/bg/:execId` (or `POST /sandboxes/:id/bg/:execId/kill`) · MCP: `sandbox_exec_kill({ sandboxId, execId })` `exec` is synchronous (60 s by default, 600 s cap): for a build, a dev server or anything that outlives the request, use background. Do not try to leave something running with `nohup` or `&` inside `exec`: the shell dies when it responds and takes the child with it. Write the command as `exec ` so the shell is REPLACED by your process instead of staying on as its parent. And **remember `sandbox_exec_kill`**: without it a hung process keeps eating the box until the TTL expires. It kills the WHOLE GROUP (SIGTERM, then SIGKILL after the grace period), so any children the command forked die too. If you lost the `execId`, `sandbox_exec_list` gives it back. ### Run inline code `POST /sandboxes/:id/run-code` Body: `{ code, lang?, timeoutSeconds? }` MCP: `sandbox_run_code({ sandboxId, code, lang? })` ### Bootstrap on resume A box restored from a snapshot comes back **without booting**: it does not re-run systemd, nor the entrypoint, nor `.bashrc` — all of that happened when the image was baked. So a box that slept for three days wakes up with the world as it was three days ago, and nothing flags it. `sandbox_set_bootstrap({ sandboxId, script, mode?, timeoutSeconds? })` `POST /sandboxes/:id/bootstrap` Body: `{ script, mode?, timeoutSeconds? }` ⚠️ **This is not a field of `POST /sandboxes`.** Create does not accept it: it is a second call on the already-created box. Create first, then declare the bootstrap on its `sandboxId`. The script is run by **the host**, on every wake-up, whatever triggered it: a request to a port's proxy, a message to the agent, the public domain. Not only when you call `resume`. ```bash git -C /data/work fetch --all --prune \ && git -C /data/work checkout -B "sesion/${EB_SANDBOX_ID}" origin/main \ && ln -sfn /skills /data/work/.claude/skills ``` - **Make it idempotent.** It runs on EVERY wake-up: `checkout -B`, not `-b`; `ln -sfn`, not `ln -s`. - Available variables: `EB_RESUME=1` and `EB_SANDBOX_ID`. The cwd is `/data/work`. - `mode: "async"` (default) — the box responds immediately while the script runs, so the first message does not pay for it. `"blocking"` waits up to `timeoutSeconds` before serving, for when the work HAS to be done first. - A failing script **never** leaves the box unreachable. The result is recorded (`eb_boot_exit`, `eb_boot_err`) so it is diagnosable instead of invisible. - Empty script = turn it off, without destroying the box. ⚠️ **Never put a credential in the script.** The recipe travels in the box's metadata and shows up in listings. Reference variables that already live inside the VM, or resolve the secret with `$secret:` from a git tool. ```js await sbx.setBootstrap({ script: 'git -C /data/work checkout -B "sesion/${EB_SANDBOX_ID}"', mode: "blocking", }); ``` ```bash curl -X POST https://www.easybits.cloud/api/v2/sandboxes/$SB/bootstrap \ -H "Authorization: Bearer $EB_KEY" -H 'Content-Type: application/json' \ -d '{"script":"git -C /data/work fetch --all","mode":"async"}' ``` This is the piece that turns skills into real memory: in a template without hot reload, an installed skill takes effect on the next wake-up, by itself. ### Git: make the agent's work outlive the box A box that sleeps for three days wakes up with three-day-old code, and without a way to publish, whatever the agent wrote dies with it. These seven tools close the full loop: clone, work, publish. ``` sandbox_git_clone({ sandboxId, repo, dir, branch?, depth?, commit?, token? }) sandbox_git_status({ sandboxId, dir }) sandbox_git_commit({ sandboxId, dir, message, addAll?, paths? }) sandbox_git_push({ sandboxId, dir, branch?, setUpstream?, token? }) sandbox_git_pull({ sandboxId, dir, rebase?, token? }) sandbox_git_checkout({ sandboxId, dir, branch, create?, from? }) sandbox_git_log({ sandboxId, dir, limit?, cursor? }) ``` **The credential is PER CALL and does not stay in the box.** `token` accepts the literal value or —better— a reference to your vault: ```js await eb.secrets.set({ name: "GITHUB_TOKEN", value: "ghp_…" }); // una vez await sb.git.clone({ repo, dir: "/data/work", token: "$secret:GITHUB_TOKEN" }); ``` The token travels to the box for that operation and is wiped when it finishes. It is **never** written to the repo's `.git/config` nor shown on the command line, so a `ps` from inside the box does not see it. That is why there is no "clean up credentials afterwards" step: there is nothing to clean. A URL with embedded credentials (`https://user:token@…`) is rejected with 422 instead of being silently accepted, precisely because git WOULD persist it. Details that matter when the caller is an agent and not a person: - `sandbox_git_status` returns data, not text: `{ branch, upstream, ahead, behind, clean, staged[], modified[], untracked[], conflicted[] }`. It comes from `porcelain=v2`, so it does not change across git versions or with the system locale. - `sandbox_git_commit` with no changes returns `{ nothingToCommit: true }` as SUCCESS. An error there invites the agent to retry, and retrying changes nothing: it is a loop. - `sandbox_git_checkout` with `create: true` uses `-B`, which is idempotent — meant to run on every start without failing with "branch already exists". - `sandbox_git_push` with `force` uses `--force-with-lease`: if someone else pushed to that branch, it fails instead of wiping out their work. - The commit identity goes per call (`authorName` / `authorEmail`, default `EasyBits Agent`), without leaving a `git config` written in the client's repo. For private repos in `launch_app`, the same mechanism: `launch_app({ repo, repoToken: "$secret:GITHUB_TOKEN" })`. The token does not enter the runspec or the release tarball. The same seven operations over REST and through the SDK: ```bash # REST — POST para clone|commit|push|pull|checkout, GET para status|log curl -X POST https://www.easybits.cloud/api/v2/sandboxes/$SB/git/clone \ -H "Authorization: Bearer $EB_KEY" -H 'Content-Type: application/json' \ -d '{"repo":"https://github.com/tu/repo.git","dir":"/data/work","token":"$secret:GITHUB_TOKEN"}' curl "https://www.easybits.cloud/api/v2/sandboxes/$SB/git/status?dir=/data/work" \ -H "Authorization: Bearer $EB_KEY" ``` ```js const sbx = await eb.sandboxes.create({ template: "node" }); await sbx.git.clone({ repo, dir: "/data/work", token: "$secret:GITHUB_TOKEN" }); await sbx.git.checkout({ dir: "/data/work", branch: "feature/x", create: true }); await sbx.git.commit({ dir: "/data/work", message: "cambios del agente" }); await sbx.git.push({ dir: "/data/work", setUpstream: true, token: "$secret:GITHUB_TOKEN" }); const st = await sbx.git.status("/data/work"); // { branch, ahead, behind, clean, ... } ``` ### Persistent kernel (code-interpreter) MCP: `sandbox_run_cell({ sandboxId, code })` — state survives between cells. Matplotlib charts come back as images. MCP: `sandbox_kernel_restart({ sandboxId })` — restart the kernel. ### Expose a port (public URL) `POST /sandboxes/:id/expose-port` Body: `{ port }` MCP: `sandbox_expose_port({ sandboxId, port })` Returns a public HTTPS URL (alive as long as the sandbox exists). If the response carries a `warning`, the service is listening **only on `127.0.0.1`** inside the box: the URL is published but will return 502 until you bind to `0.0.0.0` (or `::`). The proxy dials the guest's IP, so a loopback bind is unreachable by design — same as in Docker, Fly or Cloud Run. **Layer 7 with TLS: HTTP and WebSocket.** The certificate is already at the edge, so the same URL serves `https://` and `wss://` — no cloudflared or raw port needed for a WebSocket. What it does not do is raw layer 4: ports 22, 23, 25, 445 and 3389 are rejected with 400. For those use the L4 forward. ### Raw ports (TCP/UDP) `POST /sandboxes/:id/expose-raw` · Body: `{ port, protocol }` (`"tcp"` | `"udp"`) MCP: `sandbox_expose_raw_port({ sandboxId, port, protocol })` · SDK: `sb.exposeRawPort(port, protocol)` Close: `POST /sandboxes/:id/unexpose-raw` — MCP `sandbox_unexpose_raw_port` · SDK `sb.unexposeRawPort(port, protocol)` Returns: ```json { "hostPort": 49123, "guestPort": 22, "protocol": "tcp", "host": "cname.sandboxes.easybits.cloud", "endpoint": "cname.sandboxes.easybits.cloud:49123", "ok": true } ``` Use `endpoint` as-is for the target; do not assemble it by hand. The `hostPort` comes from a pool (49000-49999), is **different per box** and is **not** equal to the `guestPort` — that is exactly what lets each box have its own 22. It is not stable either: it is released when the box is destroyed and re-assigned, so read it again instead of storing it. It is **gated by template capability**: if the template does not declare that port, the response is 403 — that is a "no", not a transient failure; do not retry. ### SSH into a box `POST /sandboxes/:id/ssh-enable` · Body: `{ publicKeys: string[] }` MCP: `sandbox_ssh_enable({ sandboxId, publicKeys })` · SDK: `sb.enableSsh(publicKeys)` Close: `POST /sandboxes/:id/ssh-disable` — MCP `sandbox_ssh_disable` · SDK `sb.disableSsh()` **The public key comes from the CLI; do not write it by hand.** `easybits ssh-key` creates it at `~/.ssh/easybits_ed25519` the first time and always returns the same one — and it is the one `easybits ssh-proxy` uses when connecting, so they cannot drift apart. Picking another one from `~/.ssh` is the most common mistake: you inject a public key that does not match the private key you later connect with, and sshd answers `Permission denied` with everything else correct. The private key never leaves the user's machine. A single call does both halves: it injects the keys, restarts `box-sshd` and exposes 22 over L4. It returns the forward plus a ready-to-paste command: ``` ssh -p 49002 root@cname.sandboxes.easybits.cloud ``` - The box's sshd is **fail-closed**: without a key it does not start, so a box nobody injected anything into has no SSH surface, not even a closed one. That is why the key goes first. - **Key-only** access, as `root` (`PasswordAuthentication no`). - Several keys: one per array element. Internally they are separated by **comma**, not by newline. - The host key persists in `/app/ssh/`, so the fingerprint survives restarts and resume — no MITM warning on every boot. - `ssh-disable` only closes the port; the key stays injected. To truly **revoke** it, remove it from `/app/secrets.env`. - Only on templates that declare 22 (today: `ghosty-studio`). ### SSH over a tunnel (recommended: no ports, goes through 443) The command above uses a high port on the host, and **a high port does not get through an office network or a corporate VPN**. That reaches you as "it won't connect" from a network you cannot reproduce. The tunnel comes in through the usual 443: if the user can open a web page, they can get into their box. ```sh npm i -g @easybits.cloud/cli && easybits login easybits ssh-key # tu llave pública; la crea si no existe ``` In `~/.ssh/config`: ``` Host *.ghosty ProxyCommand easybits ssh-proxy %h User root ``` And that is it: ```sh ssh mi-caja.ghosty # el NOMBRE que le diste al crearla ssh sb_abc123.ghosty # el id también sirve ssh mi-caja.ghosty "cd /data/work && ghosty serve --acp" # ACP remoto por stdio ``` You still need `ssh-enable` once, to inject the key: the box's sshd is fail-closed. Pass it the output of `easybits ssh-key` — it is the same key `ssh-proxy` will use when connecting, so they cannot drift apart. The private key never leaves your machine. The box's **name** (the `name` from create) works as the host: `ssh mi-caja.ghosty`. It is neither unique nor secret — if two boxes share it the proxy fails instead of choosing, because getting into the wrong box is worse than not getting in. It does not matter that it is public: the session is authenticated with your key and the ticket, never with the name. - **The tunnel does not authenticate.** It moves opaque bytes; the SSH session is authenticated end to end between your `ssh` and the box's sshd. A tunnel failure gives nobody access. - The CLI requests a **short-lived signed ticket** (`POST /sandboxes/:id/ssh-ticket` · SDK `sb.sshTicket()`) and opens `wss://…/_ssh`. You normally do not call it yourself. - Expired ticket, tampered signature or someone else's box: **403/404** at the edge, without reaching the host. - The proxy's `stdout` is the SSH channel: any extra byte there corrupts the handshake, so all its diagnostics go to `stderr`. ### Custom domains (custom domain + automatic HTTPS) Serve a sandbox port under YOUR domain (`app.cliente.com` or `cliente.com`) instead of the `sb-…` URL. The TLS cert is issued on its own on first access (no egress fees, no extra config). One domain → one sandbox. `POST /sandboxes/:id/domain-add` · Body: `{ domain, port }` MCP: `sandbox_domain_add({ sandboxId, domain, port })` · SDK: `sb.addDomain(domain, port)` Returns in `dns` the EXACT record to create: **subdomain → CNAME** to `cname.sandboxes.easybits.cloud`; **root/apex → A** to the edge IP (apex does not allow CNAME). `POST /sandboxes/:id/domain-remove` · Body: `{ domain }` — MCP: `sandbox_domain_remove` · SDK: `sb.removeDomain(domain)` `POST /sandboxes/:id/domain-list` — MCP: `sandbox_domain_list` · SDK: `sb.listDomains()` `POST /sandboxes/:id/domain-verify` · Body: `{ domain }` — MCP: `sandbox_domain_verify` · SDK: `sb.verifyDomain(domain)` — confirms DNS + TLS cert Flow: `domain-add` → create the DNS record given in `dns` → `domain-verify`. Create the record in your **authoritative** DNS (if your registrar delegates nameservers to another provider, edit it there). ### Files - `sandbox_files_write({ sandboxId, path, content })` — write a file - `sandbox_files_read({ sandboxId, path })` — read a file - `sandbox_files_list({ sandboxId, path })` — list a directory - `sandbox_files_delete({ sandboxId, path })` — delete - `sandbox_files_move({ sandboxId, from, to })` — move/rename - `sandbox_files_mkdir({ sandboxId, path })` — create a directory - `sandbox_files_edit({ sandboxId, path, oldString, newString, replaceAll? })` — surgical in-place edit (read→replace→write). Use this instead of exec+sed: it avoids shell escaping. Replaces all occurrences by default; `replaceAll:false` = only the first. SDK: `sb.files.edit(path, old, new)` ### Logs & daemon runtime - `sandbox_logs({ sandboxId, unit?, lines?, since?, grep? })` — native journald logs (no piping journalctl through exec). REST: `POST /sandboxes/:id/logs` with that body, or `GET /sandboxes/:id/logs?unit=&lines=&grep=`. `unit` filters one systemd service (e.g. `ghosty-gc-runtime`, convention `