Servidor de Agente Claude: Construye un Wrapper WebSocket para Claude en Bun E2B

Si has estado buscando una forma limpia y probada de exponer el SDK del Agente Claude a través de una interfaz WebSocket, el repositorio claude-agent-server es exactamente lo que necesitas. Este repositorio combina lo mejor de tres mundos:

1. El SDK del Agente Claude – una poderosa API para interactuar con modelos Claude.
2. Bun – un entorno de ejecución JavaScript que compila a código máquina para un rendimiento extremo.
3. Sandboxes de E2B – un entorno seguro e aislado que se inicia bajo demanda.

En este artículo, explicaremos cómo instalar el código, construir un sandbox de E2B, conectar un cliente y ajustar la configuración del servidor. Al final tendrás un asistente estilo ChatGPT totalmente funcional que puedes ejecutar donde lo necesites.

1. ¿Qué hace el repositorio?

El repositorio claude-agent-server es un monorepo con dos paquetes principales:

Características clave:

• Despliegue E2B – El script build:e2b empaqueta el repositorio en una plantilla de sandbox reutilizable.
• WebSocket uno a uno – Solo un cliente puede conectarse a la vez, simplificando la concurrencia.
• Herramientas personalizadas – Elige herramientas permitidas, prompts del sistema y modelos vía /config antes de establecer la conexión.
• Cliente de prueba local – Ejecuta bun run test:local para probar el ejemplo empaquetado contra localhost:3000.
• Extensible – Modifica packages/server/index.ts o message-handler.ts para cambiar el comportamiento del agente o agregar nuevos comandos.

2. Prerrequisitos

Si eres nuevo en Bun, instálalo con:

curl fnm.vercel.app | bash -s -- -b "$HOME/.bun"
source "$HOME/.bun/completion.bash"

3. Clonar el repositorio e instalar dependencias

git clone https://github.com/dzhng/claude-agent-server.git
cd claude-agent-server
bun install

El repositorio incluye un archivo .env.example que define las claves requeridas:

cp .env.example .env

Edita el archivo para apuntar a tus claves API:

ANTHROPIC_API_KEY=sk-ant-·····
E2B_API_KEY=e2b_tu-clave-aquí

Tip: Mantén tus claves secretas; nunca commits el archivo .env real.

4. Construir una plantilla de sandbox de E2B

E2B ofrece sandboxes aislados bajo demanda. El servidor se empaqueta en una plantilla lista para desplegar llamada claude-agent-server.

bun run build:e2b

¿Qué ocurre bajo el capó?

1. Se crea una imagen Base Bun‑1.3.
2. El repositorio se clona dentro del sandbox.
3. bun install instala todas las dependencias de tiempo de ejecución.
4. El servidor se inicia automáticamente en el puerto 3000.
5. La plantilla resultante se publica en tu espacio de trabajo E2B.

Una vez que la compilación se complete, verás una lista de plantillas E2B con una entrada llamada claude‑agent‑server. Ya está listo para iniciarse cada vez que necesites un sandbox nuevo.

5. Usar la librería de cliente

El paquete @dzhng/claude-agent es un envoltorio ligero que maneja la creación de sandbox, la conexión WebSocket y el manejo de mensajes. Instálalo en tu proyecto:

# En tu propio directorio de proyecto
npm i @dzhng/claude-agent
# o, con Bun
bun add @dzhng/claude-agent

5.1. Ejemplo rápido

import { ClaudeAgentClient } from '@dzhng/claude-agent';

const client = new ClaudeAgentClient({
  e2bApiKey: process.env.E2B_API_KEY!,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
  template: 'claude-agent-server', // Usa el nombre de la plantilla E2B
  debug: true,
});

await client.start();

client.onMessage((msg) => {
  if (msg.type === 'sdk_message') {
    console.log('Claude:', msg.data);
  }
});

await client.send({
  type: 'user_message',
  data: {
    type: 'user',
    session_id: 'my-session',
    message: {
      role: 'user',
      content: 'Hello, Claude!',
    },
  },
});

// Cuando termines:
await client.stop();

Ciclo de vida del sandbox: El cliente crea un nuevo sandbox, lo mantiene activo hasta que llamas a stop(), y luego lo destruye automáticamente, liberando recursos.

5.2. Conectar a un servidor local

Durante el desarrollo, quizá quieras probar contra tu servidor local. El mismo cliente admite un connectionUrl:

const client = new ClaudeAgentClient({
  connectionUrl: 'http://localhost:3000',
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
});

Ahora puedes usar bun run start:server para lanzar el servidor local de Bun y ver la salida en tiempo real en la consola.

6. Personalizar el servidor

El servidor es deliberadamente ligero para que puedas extenderlo fácilmente.

6.1. Editar el núcleo

Punto de entrada principal: packages/server/index.ts. Configura las rutas HTTP y WebSocket, el manejo de configuraciones y reenvía los mensajes entrantes al SDK de Claude.

6.2. Modificar el manejo de mensajes

packages/server/message-handler.ts contiene la lógica para traducir las respuestas del SDK a mensajes JSON. Añade o cambia manejadores según sea necesario.

6.3. Añadir nuevas herramientas

El array allowedTools en la llamada /config limita las herramientas que el agente puede usar (por ejemplo, read_file, write_file). Agrega definiciones de herramientas personalizadas y expónlas a través del SDK.

7. Probar localmente

Ejecuta una instancia local y pruébala con el cliente incluido:

# En la raíz del repositorio
bun run start:server   # Inicia en http://localhost:3000

Abre otro terminal y ejecuta el cliente de prueba:

bun run test:local

Este cliente se conecta a localhost:3000, envía algunos mensajes de prueba y muestra las respuestas del SDK. Es una excelente manera de verificar cambios antes de reconstruir la imagen E2B.

8. Construir un nombre de plantilla E2B personalizado

El nombre por defecto es claude-agent-server, pero puedes cambiarlo mediante el constructor del cliente o editando el script de construcción:

const client = new ClaudeAgentClient({
  template: 'my-custom-claude-template',
  ...
});

9. Seguridad y limpieza

• El sandbox solo permanece vivo mientras tu conexión de cliente esté abierta. Cuando llamas a stop(), E2B lo elimina automáticamente.
• Las claves API se pasan ya sea vía entorno o el punto final /config. El SDK respeta la clave que proporcionas – no la expone al cliente.
• El servidor solo permite una única conexión WebSocket a la vez, evitando sobrecargas accidentales.

10. Conclusión y próximos pasos

Ahora tienes un wrapper WebSocket reutilizable para el Agente Claude, desplegable en un entorno aislado y fácilmente integrable en cualquier aplicación TypeScript o JavaScript.

• Desplegar un bot – Usa la librería de cliente en un bot de Telegram, Discord o Slack.
• Crear un agente personalizado – Extiende el servidor para añadir herramientas específicas del dominio.
• Publicar un kit de inicio – Comparte tu plantilla de sandbox con otros.

Para más detalles, consulta siempre el README completo y los comentarios en línea del código. ¡Feliz programación!