Documentación de la API

Sandboxes, web, archivos, bases de datos, documentos y hosting para agentes de IA

npx skills add https://easybits.cloud
export EASYBITS_API_KEY="eb_sk_live_…"

Instala los skills de easybits.cloud. Luego crea un sandbox `node` que sobreviva (suspendOnIdle), corre `node -v` adentro y dime el resultado con el sandboxId.

URL base: https://www.easybits.cloud/api/v2

Inicio rápido a mano

1. Crea una cuenta en easybits.cloud
2. Ve al Dashboard de Desarrollador y crea una API key
3. Haz tu primera llamada:

Obtén tu API key. Por defecto cargan solo el grupo core, para no gastar contexto. Agrega --tools docs,slides,all para más. Ver tool groups.

Authentication

All API requests require a Bearer token in the Authorization header.

Ghosty Code

El runtime agéntico con EasyBits preinstalado. Cero configuración.

Conexión en 3 pasos

1. Instala el CLI: npm install -g ghostycode (o curl -fsSL https://formmy.app/ghosty/install.sh | sh)
2. Autentica con tu key de EasyBits (sirve para LLM + MCP): ghosty auth set --provider easybits --api-key "TU_EASYBITS_API_KEY"
3. Ejecuta: ghosty --yolo

Consigue tu API key en /dash/developer. Verifica el setup con ghosty doctor y los MCPs con ghosty mcp list.

Agregar EasyBits manualmente

Si necesitas (re)agregar el servidor MCP con tu key:

Qué incluye

¿No usas Ghosty Code? EasyBits funciona con Claude Cowork, Cursor, VS Code y cualquier cliente MCP. Ver todas las opciones de conexión.

Claude Cowork (OAuth)

For Claude.ai, Cowork, and other web-based MCP clients that can't store API keys.

EasyBits implements OAuth 2.1 with Dynamic Client Registration (RFC 7591) and PKCE S256. Web MCP clients discover, register, and authenticate automatically — no API key copying, no JSON configs.

Connect in 4 steps

1. In Cowork, open Settings → Connectors → Add custom connector
2. Paste the MCP URL: https://www.easybits.cloud/api/mcp (or pick a toolset: /api/mcp/sandbox)
3. Click Connect — you'll be redirected to EasyBits to log in
4. Authorize the connector. You're done — the agent has access to your workspace

How it works

EasyBits exposes the standard OAuth discovery endpoints so any spec-compliant MCP client connects without manual setup:

Handshake flow

Notes

• Access tokens are HS256 JWTs, valid for 1 hour, with a single-use rotating refresh token.
• Consent screen: every client registered through DCR sees which app is asking and which domain it returns to before a code is issued. resource (RFC 8707) is validated: tokens are only issued for this MCP. Full guide: Claude connector.
• Additive: API key Bearer auth keeps working unchanged. The handler tries JWT verification first and silently falls through to API key validation.
• PKCE S256 is mandatory. Plain and no-PKCE flows are rejected.
• Scope: a single mcp scope — the authorized session has full access to the MCP handler.

SDK

El SDK tipado envuelve toda la REST API. Instálalo y úsalo en cualquier proyecto Node.js/Bun/Deno.

Todos los métodos

Despliega archivos subiéndolos con fileName: "sites/{websiteId}/path" — ve la sección Sitios web para el ejemplo completo.

Manejo de errores

Archivos

Operaciones en lote

Imágenes

Web

Internet para tus agentes: buscar en Google, leer cualquier página aunque bloquee bots (IPs residenciales, JS resuelto), extraer registros con esquema de sitios conocidos y rastrear un sitio completo. Disponible por REST, SDK y MCP (toolset web).

Tools MCP

Conecta https://www.easybits.cloud/api/mcp/web con tu API key como Bearer.

Ejemplo de flujo: web_search("ubiquiti u6 mesh precio", country: "mx") → tomar el link de Amazon MX → web_fetch(url, asMarkdown: true) → el agente lee título y precio. Dos consultas.

Compartir

Formularios

Crea formularios de captura hospedados — servidos en /f/:slug, sin que el usuario final necesite cuenta. Cada envío se guarda, dispara el webhook form.submitted y (si configuraste una) inserta la fila en tu base de datos. Multi-paso por secciones, condicionales y subida de archivos incluidos.

Webhooks

Recibe notificaciones POST en tiempo real cuando ocurren eventos. Los payloads se firman con HMAC SHA-256 en el header X-Easybits-Signature. Los webhooks se pausan solos tras 5 fallos de entrega consecutivos.

Verificar firmas

Formato del payload

Pagos

Genera links de pago con MercadoPago (Checkout Pro). Conecta tu cuenta en Dashboard → Pagos (pega tu access token). El dinero va directo a tu cuenta de MercadoPago — EasyBits no retiene fondos. Tools del grupo MCP payments.

Crear un link de pago

Webhook payment.paid

Email & Broadcasts

Email transaccional, audiencia con tags y newsletters one-shot — todo desde MCP. Los broadcasts agregan un pie de cancelar suscripción automáticamente y saltan a los contactos dados de baja. Tools del grupo MCP email.

Email transaccional

Audiencia + newsletter

Sitios web

Ejemplo de deploy

Endpoints

Documentos

Documentos profesionales generados con IA (reportes, folletos, catálogos, propuestas, CVs) con generación de páginas en paralelo, direcciones de diseño y temas de color semánticos.

Gestión de páginas (MCP)

Estas tools están disponibles vía MCP para edición quirúrgica a nivel de página.

Generación con IA (MCP)

Flujo de trabajo

Video

Videos editables por escenas que compilan a MP4. Cada escena es una composición HyperFrames: tú das el HTML de la escena (posicionado absoluto, assets como assets/<name>) y un snippet de timeline GSAP opcional contra un tl pausado. Agrega narración por escena → se sintetiza con kokoro (voz em_santa) y se muxea sola; la escena se estira para que la voz quepa. El render corre en un microVM on-demand (decenas de segundos) y el MP4 aterriza en tus archivos, público. Vertical 1080×1920 por default (presets: reel/story/tiktok 9:16, square 1:1, landscape 16:9).

MCP tools (12)

Agentes & Sandboxes

MicroVMs Firecracker para correr agentes y código aislado. Crea sandboxes, ejecuta comandos, expón puertos, y despliega agentes persistentes — todo desde el SDK, REST API o herramientas MCP.

Templates

Cada sandbox se crea desde un template. Estos son los disponibles:

Flujo básico: sandbox efímero

Crea un sandbox, ejecuta código, expón un puerto, destrúyelo. Ideal para ejecución aislada.

Endpoints REST

Todo el SDK corre sobre estos endpoints. Base: https://www.easybits.cloud/api/v2. Auth por header Authorization: Bearer eb_sk_live_... — ver Autenticación.

* = requerido. Un body inválido devuelve 400 con issues[] de Zod. Crear sandboxes tiene rate limit propio — ver Errores & Límites.

Snapshot & fork (clonado copy-on-write)

Congela el estado de una caja viva en una imagen nombrada (snapshot) y arranca N hijos desde ella (fork). Cada hijo es una caja independiente con su propia IP. Patrón estrella: prepara el entorno una vez (deps instaladas, proyecto listo), snapshotea, y bifurca en paralelo para probar N variantes — sin repetir el setup en cada una.

Plantillas derivadas (template-snapshot)

Preparas una caja (npm install, seeds, skills) y la capturas como plantilla derivada bajo una clave de contenido (key, hash). Desde entonces cada caja creada con ese par nace con el bootstrap hecho: sin fork ni copia por hijo, el host guarda sólo el delta de disco (12-22 MB). Medido: captura ~0.5-1 s; create desde la derivada ~0.6 s + boot ~2 s. Es lo que usa @easybits.cloud/eve-sandbox para el prewarm de eve. Diferencia con snapshot + fork: la derivada es disco solo (sin memoria) y el hijo arranca en frío; el fork ramifica una caja viva con su memoria.

Política de red por caja (network-policy)

Sólo los dominios que autorices para esa caja, o ninguno: "allow-all", "deny-all" o una allow-list por dominio ({ allow: { "api.github.com": [], "registry.npmjs.org": [] } }, sin comodines). El host la resuelve a IPs por microVM con refresco DNS, la persiste con la caja y la vuelve a aplicar al despertar. SDK: sb.setNetworkPolicy(policy) · REST: POST /sandboxes/:id/network-policy · MCP: sandbox_set_network_policy.

Exponer un puerto (URL pública)

Arranca un servidor dentro del sandbox y obtén una URL HTTPS pública al instante.

Tu servicio debe bindear a 0.0.0.0, no a 127.0.0.1: el proxy dialea la IP del guest, así que un bind a loopback es inalcanzable por diseño (igual que en Docker, Fly o Cloud Run). Si al exponer el puerto ya hay algo escuchando sólo en loopback, la respuesta trae un campo warning y la URL responderá 502 hasta que lo cambies.

Puertos raw (TCP/UDP)

sandbox_expose_port ya sirve capa 7 con TLS: HTTP y WebSocket — la misma URL responde https:// y wss://, sin túnel ni puerto raw. Lo que no hace es capa 4 cruda: los puertos 22, 23, 25, 445 y 3389 se rechazan con 400. Para un servicio que no habla HTTP usa el forward de capa 4.

• El hostPort sale de un pool (49000-49999): es distinto por caja y no es igual al puerto de adentro — así cada caja tiene su propio 22.
• No es estable: se libera al destruir la caja y se re-asigna. Vuelve a leerlo; no lo guardes ni lo pongas fijo en tu UI.
• Gateado por el template: un 403 significa "este template no tiene ese puerto". Es definitivo, no reintentes.
• Cerrarlo: sandbox_unexpose_raw_port.

SSH a una caja

Una sola llamada inyecta tu llave, reinicia el sshd de la caja y abre el 22. Te devuelve el comando listo para pegar.

La llave pública sale del CLI. No la escribas a mano ni elijas una de ~/.ssh: inyectar una pública que no corresponde a la privada con la que luego conectas da Permission denied con todo lo demás correcto, y es el error más común de este flujo.

• El sshd de la caja es fail-closed: sin llave no arranca. Por eso la llave va primero — una caja sin llave no tiene superficie SSH ni siquiera cerrada.
• Acceso solo por llave, como root. Varias llaves: una por elemento del array.
• La host key vive en /app/ssh/: el fingerprint sobrevive reinicios y resume, así que no verás el warning de MITM en cada boot.
• sandbox_ssh_disable cierra el puerto pero no revoca: para eso quita la llave de /app/secrets.env.
• Solo en templates que declaren el 22 (hoy ghosty-studio).

SSH por túnel — recomendado

El comando de arriba usa un puerto alto del anfitrión, y un puerto alto no atraviesa la red de una oficina ni una VPN corporativa. Eso te llega como “no me conecta” desde una red que no puedes reproducir. El túnel entra por el mismo 443 de siempre: si el usuario puede abrir una página web, entra a su caja.

En ~/.ssh/config:

Y ya:

• Sigue haciendo falta ssh-enable una vez, para inyectar la llave: el sshd de la caja es fail-closed. Pásale la salida de easybits ssh-key — es la misma que usa ssh-proxy al conectar, así que no pueden desfasarse. La privada nunca sale de tu máquina.
• El nombre de la caja sirve como host. No es único ni secreto: si dos cajas lo comparten el proxy falla en vez de elegir, porque entrar a la equivocada es peor que no entrar. Que sea público da igual — la sesión se autentica con tu llave y el ticket, nunca con el nombre.
• El túnel no autentica. Mueve bytes opacos; la sesión SSH se autentica de punta a punta entre tu ssh y el sshd de la caja. Un fallo en el túnel no le da acceso a nadie.
• El CLI pide un ticket firmado de vida corta (sb.sshTicket()) y abre el WebSocket. Normalmente no lo llamas tú.
• Ticket vencido, firma alterada o caja ajena: 403/404 en el borde, sin llegar al anfitrión.

Dominio personalizado (custom domain + HTTPS automático)

Sirve un puerto del sandbox bajo tu propio dominio con certificado TLS emitido automáticamente — sin egress fees, sin configurar nada de TLS. Funciona con subdominios (app.cliente.com) y dominios raíz (cliente.com).

Nota: crea el registro en tu DNS autoritativo. Si tu registrador delega los nameservers a otro proveedor (ej. Google Cloud DNS, Route53), edítalo ahí — no en el panel del registrador.

Kernel persistente (code-interpreter)

El template code-interpreter mantiene un kernel Jupyter con estado entre celdas. Variables, imports y gráficas (matplotlib) sobreviven.

Agentes persistentes (agent_create)

Crea agentes de larga duración con un endpoint HTTP público. Ideal para chatbots embebidos, asistentes en WhatsApp, o dashboards.

Agent Run (one-shot)

Dispara un agente Claude para una tarea, espera el resultado, y destruye el sandbox. Ideal para CI/CD, procesamiento por lotes, o tareas puntuales.

¿Se despierta sola?

Depende de quién le hable, y es la pregunta que más se repite:

• Agente de flota (los que corren tus conversaciones): sí. Si su caja está suspendida, el turno la reanuda antes de correr, y si el snapshot se perdió arranca una VM limpia con la memoria restaurada. No hace falta que el usuario vuelva a escribir ni que llames a sandbox_resume.
• Sandbox tuyo con tu propio servidor: no. Ahí no hay turno de agente, así que nada la reanuda por ti. Llama a sandbox_resume desde tu backend antes de usarla.

⚠️ Una conexión no despierta una caja: abrir un WebSocket contra una caja suspendida no la reanuda, negocia contra una máquina apagada. El error aparece en el cliente mientras tu servidor cree que todo fue bien. Reanuda primero, conecta después.

Bootstrap al reanudar

Una caja restaurada de un snapshot revive sin boot: no vuelve a correr systemd, ni el entrypoint, ni .bashrc. Una caja que durmió tres días despierta con el mundo de hace tres días, y nada lo señala. El bootstrap es la receta que el host corre en cada despertar, venga de donde venga (una petición al proxy de un puerto, un mensaje al agente, el dominio público) — no sólo cuando llamas a sandbox_resume.

• No es un campo de POST /sandboxes: es una segunda llamada sobre la caja ya creada.
• Hazlo idempotente — corre en CADA despertar: checkout -B, no -b; ln -sfn, no ln -s.
• Variables disponibles: EB_RESUME=1 y EB_SANDBOX_ID. El cwd es /data/work.
• Un script que falla nunca deja la caja inalcanzable: el resultado queda anotado (eb_boot_exit, eb_boot_err). Script vacío = apagarlo.
• ⚠️ Nunca metas una credencial en el script: la receta viaja en el metadata de la caja y aparece en los listados. Usa $secret: desde una tool de git.

Git: que el trabajo del agente sobreviva a la caja

Sin una forma de publicar, lo que el agente escribió muere con la caja. Siete herramientas cierran el ciclo: clonar el repo, trabajar, publicar. Es también la pieza que bootstrapea el repo de un agente (código + skills) en cada arranque.

• sandbox_git_status devuelve datos, no texto: { branch, upstream, ahead, behind, clean, staged[], modified[], untracked[], conflicted[] }. Sale de porcelain=v2, así que no cambia entre versiones de git ni con el idioma del sistema.
• sandbox_git_commit sin cambios devuelve { nothingToCommit: true } como éxito. Un error ahí invita al agente a reintentar, y reintentar no cambia nada: es un bucle.
• sandbox_git_checkout con create: true usa -B, idempotente — pensado para correrse en cada arranque sin fallar con "branch already exists".
• sandbox_git_push con force usa --force-with-lease: si alguien más empujó a esa rama, falla en vez de borrarle el trabajo.
• La identidad del commit va por llamada (authorName / authorEmail, default EasyBits Agent), sin dejar un git config escrito en el repo del cliente.
• Para repos privados en launch_app, el mismo mecanismo: launch_app({ repo, repoToken: "$secret:GITHUB_TOKEN" }). El token no entra al runspec ni al tarball del release.

Herramientas MCP del grupo sandbox

Codex con tu plan de ChatGPT

Si pagas ChatGPT Plus o Pro, ya tienes Codex incluido. Aquí lo corres en tus cajas de Easybits con ese mismo plan: sin OPENAI_API_KEY y sin pagar tokens aparte. Inicias sesión una vez con tu cuenta; tu sesión queda cifrada en tu vault (secreto CODEX_AUTH) y se pone en cualquier caja con un comando.

1. Inicia sesión una vez

En cualquier caja con Node. El comando instala Codex, te da un link y un código, espera a que entres y guarda la sesión en tu vault:

Si OpenAI te dice que el código no está permitido, activa inicio de sesión con código de dispositivo en la configuración de seguridad de ChatGPT (en un workspace lo activa el admin). ¿Ya tienes ~/.codex/auth.json en tu compu? Súbelo y te saltas este paso: easybits secrets set CODEX_AUTH < ~/.codex/auth.json.

2. Conecta cualquier caja

Para que la sesión no se muera

• OpenAI cambia el token cada vez que Codex lo renueva. Por eso connect nunca reemplaza una sesión que la caja ya tenga (con --force sí).
• Al borrar una caja por la API, su sesión renovada se guarda sola en tu vault. A mano: easybits sb codex save sb_….
• Una sesión, una caja a la vez: dos cajas renovando el mismo token se lo pisan y una tendría que volver a iniciar sesión.
• En la caja vive en ~/.codex/auth.json con permisos 600 y entra por stdin, así que no aparece en la lista de procesos.

Una caja nueva vive 30 minutos por default: créala con --ttl para trabajar más, o usa una máquina permanente. Más contexto en el post del blog.

Ghosty Lite

Un agente de verdad en su propia microVM: fork ligero de goose escrito en Rust, que habla ACP nativo. Tiene shell, edita archivos, y su disco (/data) sobrevive a que se duerma. Lo que lo distingue: corre con TU llave de EasyBits como cerebro — no traes llave de OpenAI ni de Anthropic, y el consumo se descuenta de tus tokens.

De cero a conectado

Cuatro llamadas. Cada quien con su propia llave: el agente es suyo y su consumo se descuenta de su cuenta.

1. Crear el agente

Primero tu llave (ésta la editas: pega la tuya, de Dashboard → Developer):

Y ahora sí, el comando tal cual:

2. Esperar a que esté listo y tomar la URL

Copia de la respuesta anterior el agentId y el embedToken, y guárdalos en variables:

Y consultas su estado:

3. Conectar tu cliente

La URL del paso 2 más el token del paso 1. Sin token, o con uno equivocado, responde 401.

4. Ver tu saldo

Su system prompt (identidad)

Por default el agente llega con la persona de Ghosty (habla en el idioma en que le escriben). Si quieres el tuyo, mándalo al crear con env.SYSTEM_PROMPT; con SYSTEM_PROMPT_MODE eliges si reemplaza a la de casa (replace) o se le anexa (append, el default). Después de creado se cambia con PATCH y se lee con GET …/prompt; entra sin reboot.

Una conversación ya abierta conserva el prompt con el que arrancó: el nuevo aplica a la siguiente sesión.POST /api/v2/agents/ghosty y /agents/autonomous aceptan los mismos systemPrompt / systemPromptMode en el body.

Configurarlo por API: archivos, skills, MCP, reinicio

Después de creado, el agente se configura sobre su máquina con el mismo contrato que Ghosty Studio, así que la skill ghosty-agent (npx skills add https://www.ghosty.studio) sirve aquí cambiando la base a https://www.easybits.cloud/api/v2/agents/$AGENT_ID y el bearer a tu EASYBITS_API_KEY.

Sólo para templates con máquina propia (ghosty-lite, goose); en los demás estas rutas responden 409 agente_sin_maquina. Una skill con un : sin comillas en su frontmatter se rechaza con 400 (el cargador la descartaría en silencio).

Tus propias tools (MCP)

El agente monta servidores MCP propios al abrir su sesión: los declaras al crearlo, en mcpServers. La caja ya trae node, npx y python3, así que un MCP tuyo corre sin instalar nada en la imagen.

Dos formas, las dos del protocolo ACP:

• stdio — name + command + args + env. El proceso vive dentro de la microVM.
• http / sse — type + name + url + headers. Un servidor remoto, el tuyo o el de EasyBits.

env y headers aceptan objeto { "CLAVE": "valor" } o la lista [{ "name": …, "value": … }] del protocolo; da igual cuál escribas. Un valor $secret:NOMBRE se resuelve contra tu vault al arrancar la caja — dentro del valor, así que "Bearer $secret:EASYBITS_API_KEY" queda como esperas: la credencial no queda escrita en el comando ni se guarda dos veces, y rotarla basta para que el próximo arranque tome la nueva.

La API en detalle

Lo de arriba es todo lo que hace falta. Esto es la referencia de los mismos endpoints, y dos cosas que conviene entender: running significa que EasyBits ya hizo el initialize + session/new y guardó la sesión (~6 s) — antes de eso no hay a quién mandarle el mensaje. Y el env vacío es lo normal: sólo lo llenas para cambiar de cerebro o para elegir tú el token ({ "ACP_AGENT_TOKEN": "el-tuyo" }, y entonces el embedToken deja de servir).

Hablarle por HTTP

Desde tu editor o cliente ACP

Zed, JetBrains, VS Code, Ghosty Teams o cualquier cliente ACP se conectan a la URL estable del agente. Lleva el agentId, no la máquina: si el host recicla la caja, la URL sigue siendo la misma. El token siempre va en la URL (?token=) porque es lo único que todo cliente sabe pasar — un WebSocket de navegador no puede poner cabeceras. Si el tuyo puede, Authorization: Bearer también vale.

El puerto ya está expuesto; no hace falta /expose. El cwd de la sesión es /data/work — si tu cliente manda otro que no exista en la caja, se degrada a ése.

Duerme, despierta y revive

Tras 2 h sin actividad se duerme (no muere: vive hasta 30 días). El siguiente mensaje la despierta en ~1 s con su disco y su conversación intactos, y la URL nunca cambia. Ojo si estás conectado por WebSocket: al dormirse se te cae el socket y hay que reconectar. POST /api/v2/agents/:id/revive es sólo para cuando el host recicló la caja tras días sin uso — tarda un boot (~10-60 s) y pierde el disco.

Otro cerebro (BYOK)

El default es el cerebro medido, pero el env manda. Si traes tu propia llave, el gasto va contra ese proveedor y EasyBits no lo cuenta.

Preguntas que siempre salen

Herramientas MCP

Flota

Tu flota es un grupo de agentes Ghosty que atienden tus grupos de WhatsApp 24/7. Respondes a tus clientes al instante, sin contratar a nadie y sin dejar a nadie esperando. Conectas tu WhatsApp una vez y eliges en qué grupos contesta.

Cómo conectar (WhatsApp personal)

1. Entra a /dash/flota y crea un agente.
2. Vincúlalo a tu WhatsApp: escanea el código QR (o usa el código con tu número) desde WhatsApp → Dispositivos vinculados → Vincular dispositivo.
3. Prende los grupos que quieras que atienda con los toggles. El agente solo responde en los grupos activos — los demás los ignora (anti-spam).

WhatsApp Business (WABA)

Conecta tu WhatsApp Business API oficial y tu flota atiende desde tu número oficial, sin el riesgo de bloqueo de la vinculación personal. WABA atiende conversaciones 1:1 con tus clientes (no grupos) — ideal para soporte y ventas directas. Cada número tiene su propia identidad (nombre y persona), su propio Inbox y su propio estado de respuesta.

1. En /dash/flota, sobre tu agente, pulsa Conectar WhatsApp Business. Se abre el wizard de Meta (Embedded Signup) en un popup.
2. Sigue los pasos de Meta para vincular tu cuenta de WhatsApp Business. Al terminar, el número queda asociado a ese agente.
3. Un número recién conectado arranca apagado. Elige su estado de respuesta en Conversaciones para que empiece a atender.

Inbox y estados de respuesta (por número)

Cada número WABA tiene un Inbox (botón Conversaciones): ves quién le escribe al agente, su último mensaje, y eliges con granularidad a quién responde. El estado se aplica al instante. Hay 3 estados:

• Apagado — no responde a nadie en ese número.
• Activo — responde a todos, excepto las conversaciones que pauses (cuando quieres atenderlas tú). Útil para soporte abierto.
• Solo a… — responde solo a las conversaciones que actives (lista blanca). Útil cuando estrenas el bot con un grupo reducido antes de abrirlo a todos.

En el Inbox buscas por nombre o número, ves quién está En pausa y, con un botón, pausas o reactivas el agente en cada conversación. Cualquier cambio refresca el Inbox de inmediato.

Cómo funciona: cajas

La capacidad de tu flota se compra en cajas. Cada caja corre 4 agentes Ghosty a la vez y cuesta $299 MXN/mes como suscripción mensual. ¿Necesitas atender más conversaciones al mismo tiempo? Agrega más cajas — cada caja suma 4 agentes a tu flota.

Agentes en tu app

La Flota no es sólo WhatsApp. El mismo agente atiende tu aplicación por HTTP: le mandas un mensaje, te devuelve la respuesta. No hay nada que registrar — ni grupo, ni número, ni alta previa. Y lo que configuras aquí (prompt, tools, tus propios MCP) es lo mismo que ve el agente en cualquier otro canal.

1. Hablarle

Dos formas, mismo motor: /message devuelve la respuesta completa en JSON; /message-stream la manda por SSE (chunk conforme se escribe, y un done final cuyo value es la respuesta autoritativa — arma el mensaje con ése, no concatenando los chunks). También puede llegar capacity: tu flota está llena en ese instante. No es un fallo del turno — reintenta pasado su retryAfter.

El groupId es opaco: identifica una conversación y lo eliges tú. Un web-<uuid> por usuario, o el id de tu propia tabla de chats. Mismo groupId = misma memoria; uno nuevo = conversación nueva.

2. Credenciales con alcance

El token del agente sirve para todo: mandar mensajes, cambiar el prompt, leer secretos y borrar el agente. Eso está bien para tu backend, pero no para repartirlo entre integraciones — y mucho menos para el navegador. Emite credenciales que hagan una sola cosa.

3. Embeberlo

4. Configurarlo

Todo pasa por /api/v2/fleet-agents/:id/capabilities. El dashboard de EasyBits es sólo un cliente de este endpoint: lo que puedes hacer con la UI, lo puedes hacer por API. GET devuelve el catálogo y el estado actual; POST aplica una mutación con action.

Las acciones "por canal" llevan groupId — y ahí va tu configGroupId, el mismo que mandas al hablarle.
Las marcadas ADMIN pueden sacar una credencial del vault, meter un servidor ajeno en el turno o destruir trabajo — por eso una credencial MANAGE no las alcanza.

Las mismas acciones existen por MCP: fleet_agent_list → fleet_agent_capabilities → fleet_agent_configure { fleetAgentId, action, params }, autenticadas con tu API key (no con el token del agente), en el grupo fleet del conector (?tools=fleet). Para borrar un agente: POST /api/v2/fleet-agents/:id/delete.

Tres capas de prompt

Se suman, nunca se pisan. De más estable a más volátil:

1. Base del agente — set-agent-prompt. Quién es, en todos los canales.
2. Del canal — set-prompt con groupId. Cómo se comporta en tu app.
3. Del turno — appendSystemPrompt en el propio mensaje. Quién pregunta, qué plan tiene, qué está viendo. Sin escribir nada en la config.

eve (Vercel) sobre EasyBits

eve es el framework open-source de Vercel para agentes: un agente es un directorio y cada sesión es un run durable. Cuando un agente necesita ejecutar código, eve le pide una caja a un provider de sandbox. @easybits.cloud/eve-sandbox es ese provider: cada sesión de agente corre en su propia microVM, en tu cuenta. Requiere Node ≥ 24 y eve ≥ 0.64 (para eve ≤ 0.63 fija @easybits.cloud/eve-sandbox@0.1). Ruta gratis: tu servidor eve se queda donde está (Vercel o tu laptop con eve dev/eve start) y sólo las sesiones corren en EasyBits; cabe en Byte (una conversación a la vez, sesiones de 1 h). Ruta hospedada: el servidor eve también en una caja (eve-nitro) + una caja por sesión = 2 cajas, desde Mega ($499 MXN/mes); eve-world sólo aplica ahí.

eve build llama a prepare(): caja temporal node + agent/sandbox/workspace/ en /workspace + skills en ~/.agents/skills + tu prepare(sandbox) → plantilla derivada (template-snapshot, clave de contenido, 12-24 MB, se borra sola a los 30 días sin uso; medido: 9.7 s la primera vez, 0.3 s reusada). environment.open() → start(): la caja nace de esa plantilla con todo hecho (~5 s) y entre turnos duerme y despierta en ~1 s; si el servidor reinicia, resume() la reabre, y si ya no existe falla (contrato de eve) y eve abre una sesión nueva. Egress por caja: environment.open({ networkPolicy }) o sandbox.setNetworkPolicy() en caliente (allow-all, deny-all o allow-list por dominio; transform no está soportado). Modelo: el scaffold trae un string del AI Gateway de Vercel; fuera de Vercel usa anthropic() de eve/models/anthropic (lee ANTHROPIC_API_KEY) u openai(). En local eve start responde 401 aun desde localhost: usa eve dev --no-ui. Para hospedar el servidor eve usa el template eve-nitro (Node 24, pnpm, eve CLI 0.65, /data persistente —no es el cwd: cd /data explícito—, puerto 3000), espera status=running antes de exec (sobre una caja starting responde 409 SandboxNotReady), instala con pnpm add … --allow-build=cbor-extract (pnpm 12 bloquea ese build script), sube los archivos del agente con POST /sandboxes/:id/files/write, corre npx eve build con EASYBITS_API_KEY en el env y expón el 3000; en producción eve exige auth en su API HTTP (edita agent/channels/eve.ts, p. ej. httpBasic). El estado durable (runs, hooks, streams) puede vivir en EasyBits DB con @easybits.cloud/eve-world (la caja nace con EASYBITS_DB_URL en su entorno, sin token; para retomar en una caja nueva, créala con el mismo valor, que está en metadata.eve_db_url). Landing: /eve · guía completa: /docs/eve.md · skill easybits-eve.

Sandboxes permanentes

Un sandbox efímero se auto-destruye al TTL. Una sandbox permanente corre 24/7 y se cobra flat en MXN/mes como item de suscripción encima de tu plan. Mismo recurso, mismo sandboxId — "permanente" es solo un flag + cobro. La operas igual que cualquier sandbox (exec, archivos, expose_port, dominios).

Catálogo de tiers

Precios MXN/mes, NVMe, sin cobro de tráfico. Disco add-on: +100GB NVMe = $99/mes (apilable). CPU reserved (piso garantizado por cgroup) solo desde focus. Para correr una app 24/7 (migrar desde Fly/Render) empieza en micro; nano (256MB) da para un binario estático o un side-project, no para un build de Node.

Tu app en producción en una sola llamada

launch_app es el fly launch de EasyBits: provisiona la máquina, mete el código, lo buildea, lo arranca, te da una URL HTTPS pública, publica el release de recuperación y, si le pasas un dominio, lo conecta con TLS. Te devuelve { url, releaseId, domain.dns }.

El código puede venir de tres lados: repo (git clone), archiveUrl (un .tar.gz o .zip subido desde tu compu, por si aún no tienes repo), o sandboxId (ya escribiste la app dentro de una caja). Si el build falla, la máquina que creó se libera sola — no te quedas pagando una caja rota.

Tiempos medidos con una app React Router v7 real (204 MB de node_modules, release de 49.5 MB) en tier micro: provisionar la caja 3.7 s · npm ci + build en la caja 6.9 s · publicar el release 11.3 s · redeploy a una caja limpia 12.0 s. Con prebuilt: true el deploy no ejecuta build: baja, extrae y arranca. ⚠️ Buildea dentro de la caja, no en tu Mac: un node_modules con módulos nativos compilado en macOS revienta en Linux.

Configurar la app: variables y arranque

Defaults: template: "node" (Node 24 + npm/pnpm; ubuntu no trae Node), appDir: "/app", port: 3000, build npm ci && npm run build, arranque npm start. Las variables no secretas (PORT, URLs, ids) van en env: se exportan antes del build y del arranque, y los secretos de la bóveda ganan por nombre.

Hosting sin plan: la máquina se paga sola

No necesitas plan de pago para hostear. Una máquina se factura con su propia suscripción, así que desde una cuenta Free pagas tu caja y nada más. El plan sigue siendo el gate de IA, storage y flota — dejó de serlo para hosting.

create_machine devuelve una de dos cosas: con plan, la máquina lista y cobrada en la misma factura; sin plan, un checkoutUrl que le pasas al cliente. La máquina se crea sola en cuanto el pago se confirma — nada corre gratis mientras tanto. Cancelar la máquina no toca tu plan, y cancelar tu plan no se lleva la máquina.

Crear un sandbox permanente

Releases: que tu caja sea reconstruible

Fly y Vercel pueden tratar el disco como desechable porque cada deploy lo reconstruye desde una imagen. Aquí la app se escribe dentro de la caja, así que si la caja muere no pierdes solo los datos — pierdes la app. Un release lo resuelve: un tarball versionado de tu código en almacenamiento durable, más un runspec que dice cómo construirlo y arrancarlo. Con los dos, cualquier caja se reconstruye — y eso es también como se cambia de tier (no hay resize en caliente: se recrea).

Un release guarda código, no datos. Una caja recreada arranca vacía; los datos los cubre el backup.

Backups: incluidos, 7 días

Cada noche copiamos los dataPaths de tu runspec a almacenamiento durable fuera del host, con 7 días de retención y sin costo extra. No respaldamos el sistema operativo: eso se reconstruye del template, igual que Fly respalda volúmenes y no el rootfs. Al borrar una máquina tomamos una copia final y la guardamos 7 días: borrar destruye la VM en el acto, así que ese respaldo es la única vuelta atrás.

Dos cosas dichas de frente: el RPO es de 24 horas, y el backup se toma del filesystem en caliente, así que una base de datos escribiendo durante la copia puede quedar inconsistente — cada backup reporta su nivel en el campo consistency. Si tu app tiene una DB, tenla fuera de la caja (libSQL de EasyBits, Atlas) o toma un create_backup tras detenerla.

Promover un efímero a permanente

Levanta un sandbox, pruébalo, y si quieres conservarlo hazlo permanente — conserva el mismo sandboxId, desarma el reaper y arranca el cobro.

Variables secretas de tu app

Tu app necesita su DATABASE_URL, su STRIPE_SECRET_KEY. No las metas en runspec.env: eso se guarda en la base y viaja dentro de cada tarball de release. La API las rechaza por nombre.

Los valores se guardan cifrados en tu bóveda y en el runspec queda solo la lista de nombres. Se materializan dentro de la máquina —en un archivo que solo root puede leer— justo antes de construir y de arrancar. No entran al release: una caja reconstruida desde un tarball sigue sin llevarlos dentro, pero sabe cuáles pedir.

Surten efecto en el siguiente despliegue, no al vuelo: rotar un secreto es cambiarlo aquí y volver a desplegar. Si el runspec declara uno que no está en la bóveda, el deploy falla diciendo cuál — mejor que ver la app morir al conectar. También se administran en /dash/hosting → pestaña Variables.

Desplegar desde GitHub en cada push

El patrón recomendado para el sitio de un cliente: construir en el runner de GitHub y mandarle a la máquina el resultado ya hecho. La caja no compila nada, así que un sitio que necesitaría 4 GB para bundlear cabe en micro.

Por qué sandboxId y archiveUrl juntos: sandboxId es el destino, no una fuente. Puedes mandar un artefacto ya construido a una máquina que ya existe — sin eso, el único sitio donde podría ocurrir el build sería dentro de la caja del cliente.

Bases de datos

Crea bases de datos SQLite aisladas para tus agentes y apps — una por cliente, proyecto o recurso. Corren sobre sqld (libsql-server), con scale-to-zero: no pagas cómputo cuando nadie consulta. Cada DB es un namespace independiente; tu agente las crea, consulta y llena sin que escribas backend.

Crear y consultar

Herramientas MCP del grupo databases

Secretos

Guarda credenciales (API tokens, OAuth, llaves) cifradas AES-256-GCM en tu cuenta. Un secreto es write-only: una vez guardado, su valor nunca se puede volver a leer por API ni MCP — solo se inyecta como variable de entorno dentro de un sandbox vía agent_run({ secrets: [nombre, ...] }). Es también donde vive el OAuth que usa tu Flota.

Herramientas MCP del grupo secrets

LLM (OpenAI-compatible)

Un gateway OpenAI-compatible con tu misma llave de EasyBits. No necesitas cuenta con el proveedor ni otra API key: apuntas cualquier cliente OpenAI a nuestra base URL y el consumo se descuenta de tu saldo de tokens.

Base URL

Endpoints

Notas

• Modelos: no hardcodeamos la lista — pégale a /models. Si omites model, el default es deepseek-chat.
• La llave necesita scope WRITE: gastar tokens no es una operación de lectura. Una llave de solo lectura recibe 403 permission_error.
• Se cobra prompt_tokens + completion_tokens de cada respuesta contra tu saldo. Sin saldo: 402 insufficient_quota, con used y limit en meta.
• Headers de respuesta: x-llm-tokens-remaining y x-ratelimit-remaining-requests — úsalos para no tener que pedir el balance en cada llamada.
• CORS abierto, pero eso no hace segura una llave en el browser: eb_sk_live_... es secreta y gasta tu saldo. Llama desde tu servidor.
• Contextos largos cuestan: cada turno reenvía el historial completo y se cobra íntegro. Una conversación de 300K tokens paga 300K por turno. Compacta o recorta.

Llamadas

Salas de videollamada con grabación en HD, self-hosted (template livekit-svc). Tu agente crea la sala, los participantes se unen desde el navegador (cámara + pantalla compartida, sin instalar nada), y el servidor graba el layout completo en 1080p. Al terminar, el MP4 se sube a tus Archivos. Sin servidores de terceros, sin límite de duración.

Crear una llamada y grabar

create levanta la sala y devuelve roomUrl — compártelo con los participantes. La sala se auto-destruye a las 3 horas si no la cierras antes.

Estado, archivos y cierre

status reporta si está grabando y quién está conectado; files lista las grabaciones; destroy cierra la sala limpiamente (sube grabaciones pendientes y libera la VM).

Transcript de la llamada

Al detener la grabación, la caja transcribe el audio con Whisper embebido (español, on-device — sin proveedor externo) y sube el .txt a tus Archivos. transcript devuelve el texto inline (no un link) más un status: transcribing (Whisper procesando, reintenta en ~1 min), ready (texto en text), failed, unavailable o no_recording. Con sandboxId = estado en vivo del box; sin él = el transcript más reciente de Archivos.

Cuenta & Uso

Errores & Límites

Tool Groups

Por defecto el servidor MCP carga solo el grupo core para minimizar el uso de tokens. Habilita grupos adicionales para desbloquear más capacidades.

Uso