Los agentes cuentan con sus propias computadoras dentro de Sandboxes en disponibilidad general

Cuando lanzamos Cloudflare Sandboxes el pasado junio, la premisa era simple: los agentes de IA necesitan desarrollar y ejecutar código, y deben hacerlo en un lugar seguro.

Si un agente trabaja como un desarrollador, implica tareas como clonar repositorios, programar en distintos lenguajes, ejecutar servidores de prueba, entre otras actividades. Para hacer estas tareas de manera eficaz, a menudo necesitarán una computadora completa (y si no la necesitan, pueden optar por una opción más ligera).

Muchos desarrolladores están armando soluciones con máquinas virtuales o de contenedores ya existentes, pero hay muchos desafíos complejos por resolver:

• Escalabilidad repentina. Como cada sesión necesita su propio sandbox, suele ser necesario iniciar muchos de ellos rápidamente, pero sin tener que pagar por recursos de cómputo que permanecen inactivos.

• Restauración rápida del estado. Cada sesión debe comenzar y reiniciarse rápidamente, reanudando el estado anterior.

• Seguridad. Los agentes necesitan acceder a los servicios de manera segura, pero no es conveniente confiarles las credenciales.

• Control. Debe ser sencillo controlar de forma automática el ciclo de desarrollo del sandbox, ejecutar comandos, gestionar archivos y otras tareas.

• Ergonomía. Debes ofrecer una interfaz sencilla para que tanto los humanos como los agentes realicen operaciones comunes.

Hemos dedicado tiempo a resolver estos problemas para que tú no tengas que hacerlo. Desde nuestro lanzamiento inicial, hemos convertido a los Sandboxes en un entorno aún más eficiente para ejecutar agentes a escala. Hemos colaborado con nuestros socios iniciales, como Figma, que ejecutan agentes en contenedores mediante Figma Make:

“Figma Make está diseñado para ayudar a desarrolladores y creadores de todo tipo a pasar de la idea a la producción con mayor rapidez. Para lograr ese objetivo, necesitábamos una solución de infraestructura que ofreciera sandboxes confiables y altamente escalables donde pudiéramos ejecutar código no confiable creado por agentes y usuarios. Cloudflare Containers brinda esa solución".

- Alex Mullans, IA y plataformas para desarrolladores en Figma

Queremos que Sandboxes llegue a más organizaciones destacadas, y por eso hoy nos complace anunciar que tanto Sandboxes como Cloudflare Containers ya están disponibles de forma general.

Veamos algunos de los cambios recientes en Sandboxes:

• La inyección segura de credenciales te permite hacer llamadas autenticadas sin que el agente tenga acceso a las credenciales  

• El soporte de PTY te brinda a ti y a tu agente una terminal real

• Los intérpretes de código persistentes ofrecen a tu agente un entorno listo para ejecutar Python, JavaScript y TypeScript con estado desde el inicio

• Los procesos en segundo plano y las URL de vista previa en vivo ofrecen una forma sencilla de interactuar con los servidores de desarrollo y verificar los cambios en curso

• La supervisión del sistema de archivos acelera el proceso de iteración cuando los agentes realizan cambios

• Las instantáneas te permiten recuperar rápidamente la sesión de codificación de un agente

• Los límites más amplios y el precio activo de la CPU permiten implementar una flota de agentes a escala sin tener que pagar por ciclos de CPU que no se utilizan

Antes de revisar algunos de los cambios recientes, hagamos un repaso rápido de los conceptos básicos.

Un Cloudflare Sandbox es un entorno persistente y aislado con la tecnología de Cloudflare Containers. Solicitas un sandbox por nombre. Si se está ejecutando, lo tienes disponible. Si no es así, se inicia. Cuando está inactivo, entra automáticamente en reposo y se reactiva al recibir una solicitud. Es fácil interactuar de forma automática con el sandbox mediante métodos como exec, gitClone, writeFile y y otros.

import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";

export default {
  async fetch(request: Request, env: Env) {
    // Ask for a sandbox by name. It starts on demand.
    const sandbox = getSandbox(env.Sandbox, "agent-session-47");

    // Clone a repository into it.
    await sandbox.gitCheckout("https://github.com/org/repo", {
      targetDir: "/workspace",
      depth: 1,
    });

    // Run the test suite. Stream output back in real time.
    return sandbox.exec("npm", ["test"], { stream: true });
  },
};

Siempre que proporciones el mismo ID, las solicitudes posteriores podrán acceder a ese mismo sandbox desde cualquier lugar del mundo.

Uno de los mayores desafíos en las cargas de trabajo de agentes es la autenticación. A menudo necesitas que los agentes accedan a servicios privados, pero no puedes confiarles las credenciales sin protección. 

Los sandboxes resuelven este problema inyectando credenciales en la capa de red mediante un proxy de salida programable. Esto significa que los agentes en el sandbox nunca tienen acceso a las credenciales y que puedes personalizar completamente la lógica de autenticación según tus necesidades.

class OpenCodeInABox extends Sandbox {
  static outboundByHost = {
    "my-internal-vcs.dev": (request, env, ctx) => {
      const headersWithAuth = new Headers(request.headers);
      headersWithAuth.set("x-auth-token", env.SECRET);
      return fetch(request, { headers: headersWithAuth });
    }
  }
}

Para obtener información detallada sobre cómo funciona esto — que incluye la inyección de credenciales con reconocimiento de identidad, la modificación dinámica de reglas y la integración con enlaces de Workers — lee nuestra publicación reciente del blog sobre autenticación de Sandbox.

Los primeros sistemas de agentes solían modelar el acceso al shell como un ciclo de solicitud y respuesta: ejecutar un comando, esperar la salida, insertar la transcripción en el prompt y repetir. Funciona, pero no es así como los desarrolladores realmente usan una terminal. 

Las personas ejecutan un proceso, observan cómo llega a la salida, lo interrumpen, se vuelven a conectar más tarde y continúan. Los agentes también se benefician de ese mismo ciclo de retroalimentación.

En febrero, incorporamos la compatibilidad con PTY. Una sesión de pseudoterminal en un sandbox, redireccionada mediante proxy a través de WebSocket, compatible con xterm.js.

Simplemente llama a sandbox.terminal para atender el backend:

// Worker: upgrade a WebSocket connection into a live terminal session
export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);
    if (url.pathname === "/terminal") {
      const sandbox = getSandbox(env.Sandbox, "my-session");
      return sandbox.terminal(request, { cols: 80, rows: 24 });
    }
    return new Response("Not found", { status: 404 });
  },
};

Y utiliza xterm addon para llamarlo desde el cliente:

// Browser: connect xterm.js to the sandbox shell
import { Terminal } from "xterm";
import { SandboxAddon } from "@cloudflare/sandbox/xterm";

const term = new Terminal();
const addon = new SandboxAddon({
  getWebSocketUrl: ({ origin }) => `${origin}/terminal`,
});

term.loadAddon(addon);
term.open(document.getElementById("terminal-container")!);
addon.connect({ sandboxId: "my-session" });

Esto permite que los agentes y desarrolladores utilicen un PTY completo para depurar esas sesiones en vivo.

Cada sesión de terminal tiene su propio shell aislado, su propio directorio de trabajo y su propio entorno. Abre tantas como necesites, como lo harías en tu propia máquina. La salida se almacena en el servidor, de modo que al reconectarte se reproduce lo que te perdiste.

Para el análisis de datos, la creación de scripts y los flujos de trabajo exploratorios, también ofrecemos una abstracción de nivel superior: un contexto persistente de ejecución de código.

La palabra clave es "persistente". Muchas implementaciones de intérpretes de código ejecutan cada fragmento de manera aislada, por lo que el estado se pierde entre llamadas. No se puede establecer una variable en un paso y leerla en el siguiente.

Los sandboxes permiten crear "contextos" que mantienen el estado de manera persistente. Las variables y las importaciones se mantienen entre llamadas, de la misma manera que en un anotador de Jupyter:

// Create a Python context. State persists for its lifetime.
const ctx = await sandbox.createCodeContext({ language: "python" });

// First execution: load data
await sandbox.runCode(`
  import pandas as pd
  df = pd.read_csv('/workspace/sales.csv')
  df['margin'] = (df['revenue'] - df['cost']) / df['revenue']
`, { context: ctx });

// Second execution: df is still there
const result = await sandbox.runCode(`
  df.groupby('region')['margin'].mean().sort_values(ascending=False)
`, { context: ctx, onStdout: (line) => console.log(line.text) });

// result contains matplotlib charts, structured json output, and Pandas tables in HTML

Los agentes son más útiles cuando pueden crear algo y mostrárselo al usuario de inmediato. Los sandboxes admiten procesos en segundo plano, verificaciones de disponibilidad y URL de vista previa. Esto permite que un agente inicie un servidor de desarrollo y comparta un enlace en vivo sin abandonar la conversación.

// Start a dev server as a background process
const server = await sandbox.startProcess("npm run dev", {
  cwd: "/workspace",
});

// Wait until the server is actually ready — don't just sleep and hope
await server.waitForLog(/Local:.*localhost:(\d+)/);

// Expose the running service with a public URL
const { url } = await sandbox.exposePort(3000);

// url is a live public URL the agent can share with the user
console.log(`Preview: ${url}`);

Con waitForPort() y waitForLog(), los agentes pueden secuenciar el trabajo en función de señales reales del programa en ejecución en lugar de conjeturas. Esto es mucho mejor que una alternativa habitual, que suele ser alguna variante de sleep(2000) y confiar en que funcione.

Los ciclos modernos de desarrollo son impulsados por eventos. Guarda un archivo, vuelve a ejecutar la compilación. Edita una configuración, reinicia el servidor. Cambia una prueba, vuelve a ejecutar la suite.

Lanzamos sandbox.watch() en marzo. Devuelve un flujo SSE respaldado por inotify nativo, el mecanismo del kernel que Linux que gestiona los eventos del sistema de archivos.

import { parseSSEStream, type FileWatchSSEEvent } from '@cloudflare/sandbox';

const stream = await sandbox.watch('/workspace/src', {
  recursive: true,
  include: ['*.ts', '*.tsx']
});

for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
  if (event.type === 'modify' && event.path.endsWith('.ts')) {
    await sandbox.exec('npx tsc --noEmit', { cwd: '/workspace' });
  }
}

Este es uno de esos elementos básicos que, de manera silenciosa, transforman lo que los agentes pueden hacer. Un agente que puede observar el sistema de archivos en tiempo real puede participar en los mismos ciclos de retroalimentación que un desarrollador humano.

Imagina a un desarrollador (humano) trabajando en su laptop. Hacen un git clone de repositorio, ejecutan npm install, escriben código, envían un PR y luego cierran la laptop mientras esperan la revisión del código. Cuando llega el momento de retomar la tarea, solo tienen que volver a abrir la laptop y continuar donde la dejaron.

Si un agente quiere replicar este flujo de trabajo en una plataforma de contenedores básica, se encuentra con un inconveniente. ¿Cómo retomas rápidamente donde lo dejaste? Podrías mantener un sandbox en funcionamiento, pero luego pagarías por los recursos de cómputo inactivos. Podrías comenzar desde cero con la imagen del contenedor, pero entonces tendrías que esperar un largo git clone y un npm install.

Nuestra respuesta son las instantáneas, que se implementarán en las próximas semanas.

Una instantánea conserva todo el estado del disco del contenedor, la configuración del sistema operativo, las dependencias instaladas, los archivos modificados, los archivos de datos y más. Luego, te permite restaurarlo rápidamente más tarde.

Puedes configurar un Sandbox para que tome instantáneas automáticamente cuando entre en modo de suspensión.

class AgentDevEnvironment extends Sandbox {
  sleepAfter = "5m";
  persistAcrossSessions = {type: "disk"}; // you can also specify individual directories
}

También puedes tomar una instantánea de forma programática y restaurarla manualmente. Esto resulta útil para crear puntos de control del trabajo o para bifurcar sesiones. Por ejemplo, si quisieras ejecutar cuatro instancias de un agente en paralelo, podrías iniciar fácilmente cuatro sandboxes desde el mismo estado.

class AgentDevEnvironment extends Sandbox {}

async forkDevEnvironment(baseId, numberOfForks) {
  const baseInstance = await getSandbox(baseId);
  const snapshotId = await baseInstance.snapshot();

  const forks = Array.from({ length: numberOfForks }, async (_, i) => {
    const newInstance = await getSandbox(`${baseId}-fork-${i}`);
    return newInstance.start({ snapshot: snapshotId });
  });

  await Promise.all(forks);
}

Las instantáneas se almacenan en R2 dentro de tu cuenta, lo que te brinda durabilidad e independencia de ubicación. El sistema de alojamiento en caché de R2 permite restauraciones rápidas en todo el mundo.

En futuras versiones, también se capturará el estado de la memoria en vivo, lo que permitirá que los procesos en ejecución se reanuden exactamente donde se quedaron. Una terminal y un editor se volverán a abrir en el mismo estado en el que estaban cuando se cerraron por última vez.

Si te interesa restaurar el estado de la sesión antes de que las instantáneas estén disponibles, puedes utilizar hoy mismo los métodos de copia de seguridad y restauración. Estos también permiten conservar y restaurar directorios usando R2, pero no son tan eficientes como las verdaderas instantáneas a nivel de máquina virtual. Aun así, todavía pueden generar mejoras considerables en la velocidad frente a la recreación poco optimizada del estado de la sesión.

^{El inicio de un sandbox, la clonación de "axios" y la ejecución de npm lleva 30 segundos. La restauración desde una copia de seguridad lleva 2 segundos.}

Mantente atento al lanzamiento oficial de las instantáneas.

Desde nuestro lanzamiento inicial, hemos ido aumentando constantemente la capacidad. Los usuarios de nuestro plan de precios estándar ahora pueden ejecutar 15 000 instancias concurrentes del tipo lite, 6000 instancias de tipo básico y más de 1000 instancias concurrentes de tipos más grandes. Contáctanos para ejecutar aún más instancias.

También cambiamos nuestro modelo de precios para que el funcionamiento a escala sea más rentable. Los sandboxes ahora solo cobran por los ciclos de CPU que se usan activamente. Esto significa que no estás pagando por la CPU inactiva mientras tu agente espera la respuesta de un LLM.

Hace nueve meses, lanzamos un sandbox que podía ejecutar comandos y acceder a un sistema de archivos. Eso fue suficiente para probar el concepto.

Lo que tenemos ahora es diferente en esencia. Hoy, un sandbox funciona como un entorno de desarrollo completo: incluye un terminal que puede vincularse con un navegador, un intérprete de código con estado persistente, procesos en segundo plano con URL de vista previa en tiempo real, un sistema de archivos que notifica cambios al instante, proxies de salida para la inyección segura de credenciales, y un mecanismo de instantáneas que permite reinicios rápidos casi inmediatos. 

Al desarrollar sobre esta base, empieza a tomar forma un patrón interesante: agentes capaces de realizar un auténtico trabajo de ingeniería.Clona un repositorio, instálalo, ejecuta las pruebas, lee los errores, edita el código, vuelve a ejecutar las pruebas. Ese tipo de ciclo de retroalimentación ágil que hace efectivo a un ingeniero humano — ahora también lo aprovecha el agente.

Estamos en la versión 0.8.9 de SDK. Empieza hoy mismo:

npm i @cloudflare/sandbox@latest