SandBase Harness

Runtime autoalojado local-first y puente MCP stdio para sesiones auditables de agentes de IA.

GitHub
643
Prueba este MCPPatrocinado

Documentación

SandBase Harness

English | 中文

GitHub stars Listed on deepseek-plugin.org Release Official MCP Registry Discussions CodeQL License

Metadatos del proyecto legibles por IA: llms.txt · guía de instalación

Un runtime local-first para agentes de IA. Sesiones, herramientas en sandbox, memoria, credenciales, registros de auditoría y una consola integrada, todo ejecutándose en tu máquina o en tu propia infraestructura.

¿Estás construyendo con DeepSeek Harness? El Manual de DeepSeek Harness independiente proporciona guías de runtime respaldadas por el código fuente, solución de problemas multilingüe y un mapa de recursos agent-first actualizado periódicamente.

SandBase Harness architecture

¿Buscas un puente ligero en lugar de un runtime completo? SandBase CLI conecta 25 clientes de IA a más de 2,000 modelos y APIs mediante un puente MCP stdio local. Si se ajusta a tu flujo de trabajo, dale una estrella a SandBase CLI para que otros usuarios de agentes puedan descubrirlo.

¿Necesitas APIs alojadas de modelos y medios? SandBase ofrece una interfaz única para APIs de generación de LLM, imagen y video, con la guía de inicio rápido de API que cubre claves y primeras llamadas.

git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build
mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start
# open http://127.0.0.1:3000/dashboard

Elige SandBase Harness cuando necesites más que un bucle de modelos:

NecesidadLo que Harness proporciona
Ejecutar código generado de forma seguraSandboxes de trabajadores locales, Docker, Kubernetes y autoalojados
Inspeccionar agentes de larga duraciónSesiones persistentes, flujos de eventos reanudables, auditoría y reproducción
Controlar el acceso a herramientasConjuntos de herramientas MCP, bóvedas de credenciales, políticas de permisos y aprobaciones
Operar cualquier modeloOpenAI, Anthropic, MiniMax y proveedores compatibles con OpenAI, incluido DeepSeek V4
Mantener tu infraestructura tuyaAlmacenamiento local-first con SQLite y archivos, sin plano de control alojado obligatorio

Si este runtime resuelve un problema real de infraestructura de agentes para ti, dale una estrella al repositorio para que otros desarrolladores puedan encontrarlo.

Encuentra SandBase Harness

El proyecto también es descubrible a través de estos directorios independientes del ecosistema:

Referencias comunitarias verificadas recientemente:

Revisión comunitaria pendiente:

Pruébalo en Codespaces

Open in GitHub Codespaces

El contenedor de desarrollo incluido instala dependencias y compila el runtime. Cuando la terminal esté lista, inicia el servidor en el puerto reenviado:

node dist/index.js start --host 0.0.0.0

Abre el puerto reenviado de la Consola de SandBase Harness y luego configura un modelo en Configuración > Modelos. El uso de Codespaces puede facturarse a través de GitHub; el inicio rápido local que aparece a continuación sigue siendo gratuito y mantiene todos los datos del runtime en tu máquina.

Por qué

Los SDK de agentes manejan el bucle del modelo. Los agentes de producción necesitan más: sesiones persistentes, gobernanza de herramientas, límites de sandbox, manejo de credenciales, memoria, auditabilidad y una interfaz para que los humanos inspeccionen lo que sucedió. managed-agents es esa capa de runtime — no un constructor visual de flujos de trabajo ni otro SDK de modelos.

Características

  • API de /v1 estilo Claude Managed Agents y Consola local
  • Agentes, sesiones, entornos, bóvedas de credenciales, almacenes de memoria, archivos, habilidades y claves API respaldados por SQLite — metadatos SQLite por defecto
  • Bytes de archivos/habilidades locales almacenados en el directorio de estado del espacio de trabajo
  • Eventos enviados por el servidor reanudables para reproducción y depuración de sesiones
  • Un límite activo de proveedor de modelos configurado a través de Configuración V2
  • Backends de sandbox: proceso local, Docker (contenedores por sesión), Kubernetes (kubectl exec/cp), cola de trabajadores autoalojada
  • Configuración V2: un proveedor de modelos del espacio de trabajo, motor de bucle, almacenamiento, memoria, sandbox — con validación, modos de formulario/JSON y flujo de reinicio
  • Conjuntos de herramientas MCP, políticas de permisos, herramientas integradas y paquetes de habilidades
  • Puente DeepSeek Harness sobre MCP stdio para agentes, sesiones, turnos transmitidos, artefactos y cancelación
  • SDK de TypeScript en managed-agents/sdk
  • Puerta de publicación: npm run release:check

Capturas de pantalla

Resumen de la consolaConfiguraciónReferencia de API
overviewsettingsapi-ref

Comienza con un caso de uso

Consulta la Vitrina para ver tres rutas prácticas: un agente de codificación auditable, DeepSeek Harness como interfaz interactiva y ejecución de código controlada en sandboxes Local, Docker, Kubernetes y autoalojados.

Para la configuración específica del cliente, consulta la guía de instalación, incluido el comando fijado de Cline CLI y la configuración del Puente MCP de Docker.

Discusiones de casos de uso de la comunidad:

Requisitos

  • Node.js 22+
  • npm 10+
  • Una clave API de proveedor de modelos (OpenAI, Anthropic, MiniMax o un endpoint compatible con OpenAI)
  • Docker (opcional, para sandboxes respaldados por Docker)

DeepSeek Harness

Ejecuta este proyecto como un plugin de DSH en lugar de tratar dsh-plugin solo como metadatos de descubrimiento. Instala el paquete en un perfil de DSH, inicia managed-agents y luego arranca ese perfil:

export MANAGED_AGENTS_URL=http://127.0.0.1:3000
# Preferred: install a local source checkout after `npm run build`.
dsh plugin --profile web add -w ../sandbase-harness
# Git URL fallback. Keep HTTPS; do not convert the spec to SSH.
# dsh plugin --profile web add git+https://github.com/sandbaseai/sandbase-harness.git
dsh web

Si Plugin Hub informa already installed: managed-agents después de una instalación parcial o repetida, actualiza primero el Hub, luego elimina solo la entrada de plugin managed-agents mostrada y reintenta desde la fuente Git HTTPS etiquetada:

dsh plugin --profile web update dsh-plugin
dsh plugin --profile web remove managed-agents
dsh plugin --profile web add git+https://github.com/sandbaseai/sandbase-harness.git

Esta es una ruta de instalación duplicada de Plugin Hub, no una ruta de instalación npm. Si la vista instalada muestra un identificador de destino diferente, elimina ese identificador exacto. Mantén el directorio del perfil y su evidencia hasta que el runtime se inicie correctamente; consulta el problema de recuperación informado.

El perfil instala directamente la copia de código fuente verificada; no resuelve el paquete npm no relacionado sin ámbito. Una instalación alojada en Git ejecuta prepare solo cuando falta dist/. Mantén la especificación Git HTTPS; convertirla a SSH falla en hosts Windows sin acceso SSH a GitHub.

Una instalación alojada en Git necesita un paso adicional para la lista de permitidos de compilación de pnpm. El primer dsh plugin --profile web add falla con ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED e imprime la clave exacta. Agrega esa clave bajo allowBuilds: en el pnpm-workspace.yaml del perfil, luego vuelve a ejecutar el mismo comando add; un nombre de paquete simple no coincide con una resolución alojada en Git:

allowBuilds:
  "managed-agents@https://codeload.github.com/sandbaseai/sandbase-harness/tar.gz/<commit>": true

La segunda ejecución compila dist/ a través de prepare, crea los bins managed-agents / managed-agents-mcp y se une a la capa del paquete. El parche inicia la entrada MCP empaquetada sobre stdio. DSH puede entonces listar agentes, crear y ejecutar sesiones, inspeccionar resultados y artefactos, y detener el trabajo a través de herramientas nativas de mcp__sandbase__*. Consulta examples/deepseek-harness para la lista completa de herramientas y la configuración del runtime autenticado.

Para un recorrido que comienza con DSH y agrega este runtime como un plugin real de terceros, lee la guía para desarrolladores de DeepSeek Harness. La edición en chino también está disponible; ambos artículos se mantienen contra la integración fijada de SandBase Harness v0.3.8.

Combina el plugin con SandBase Skills para darle al mismo proyecto DSH un flujo de trabajo de investigación portátil y verificable por fuente:

npx --yes github:sandbaseai/sandbase-skills add multi-source-search
dsh web

Esto instala la Skill completa en .dsh/skills/multi-source-search, el directorio de descubrimiento a nivel de proyecto de DSH. Se ejecuta desde la fuente de GitHub y no necesita una cuenta de SandBase cuando DSH ya proporciona herramientas web/búsqueda.

Para un flujo de trabajo completo y reproducible que combine el libro de evidencia con ejecución en sandbox, credenciales, auditoría y reproducción, lee Construye un Agente de Investigación Auditable.

¿Nuevo en perfiles DSH, composición de plugins, política de herramientas o semántica de sesiones? El Manual de DeepSeek Harness independiente proporciona inicios rápidos respaldados por fuente, mapas de arquitectura y solución de problemas para las capas de runtime utilizadas por esta integración. Lee su https://sandbaseai.github.io/deepseek-harness-handbook/sandbase-harness-bridge.html para el contrato específico de DSH, luego comienza con el Install Doctor de navegador local para evidencia de instalación, o usa el Failure Router para identificar el primer límite de runtime roto.

Inicio rápido

git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build
mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

Abre http://127.0.0.1:3000/dashboard, ve a Configuración > Modelos, pega tu clave API y ya estás en marcha.

El nombre managed-agents sin ámbito en npm no es este proyecto. Hasta que se anuncie un paquete oficial con ámbito en este repositorio, instala solo desde la fuente de GitHub etiquetada que se muestra arriba. No ejecutes npx managed-agents ni npm install managed-agents.

El puente MCP de seis herramientas se publica como una imagen OCI multiarquitectura. Inicia la API de Harness y luego agrega este comando stdio a un cliente MCP:

Paquete de contenedor: Registro de contenedores de GitHub

docker pull ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8
docker run --rm -i \
  -e MANAGED_AGENTS_URL=http://host.docker.internal:3000 \
  ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8

Para un runtime remoto autenticado, también pasa MANAGED_AGENTS_API_KEY. La imagen del contenedor contiene solo el puente MCP; las sesiones de agentes y el trabajo en sandbox permanecen en el runtime de Harness conectado. Cada imagen de publicación se compila desde la etiqueta Git correspondiente para linux/amd64 y linux/arm64, incluye metadatos de fuente OCI y propiedad de MCP, y recibe una atestación de procedencia de compilación de GitHub.

Plugin de agente portátil

Copilot CLI, VS Code y otros clientes de Agent Plugins 1.0 pueden instalar el mismo puente MCP respaldado por OCI directamente desde este repositorio. Inicia primero la API de Harness y Docker, luego expón su URL al proceso del plugin:

export MANAGED_AGENTS_URL=http://host.docker.internal:3000
# Optional when the runtime requires authentication:
export MANAGED_AGENTS_API_KEY=your-runtime-key

copilot plugin install sandbaseai/sandbase-harness:agent-plugin

El plugin pasa estas variables de entorno a la imagen fijada ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8. No almacena una clave en plugin.json, mcp.json ni en los archivos del plugin instalado. En Linux, el comando Docker del plugin mapea host.docker.internal a través de host-gateway.

Para desarrollo desde la rama más reciente main:

git clone https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness && npm ci && npm run build
cd .. && mkdir my-agents-dev && cd my-agents-dev
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

Diseño del espacio de trabajo

my-agents/
├── agents/                  # Seed agent definitions (YAML)
│   └── assistant.yaml
├── skills/                  # Seed skill packages
│   └── example-skill/
│       └── SKILL.md
└── .managed-agents/         # Runtime state (gitignored)
    ├── config.yaml          # Workspace configuration
    ├── data.db              # SQLite metadata
    ├── logs/runtime.log
    ├── files/               # Uploaded file bytes
    ├── skills/              # Uploaded skill packages
    ├── snapshots/           # Session workspace snapshots
    └── sandbox/             # Local session sandboxes

Configuración

.managed-agents/config.yaml:

model:
  provider: openai
  api_key: ${OPENAI_API_KEY}

storage:
  metadata: { provider: sqlite, options: {} }
  artifacts: { provider: local, options: { base_path: files } }

Los agentes eligen IDs de modelo concretos (gpt-4o, claude-sonnet-4-20250514, openai/gpt-5.5). La configuración del espacio de trabajo solo indica cómo llegar al servicio de modelos.

Para la configuración de DeepSeek V4 Pro/Flash, incluido el esfuerzo máximo de razonamiento, consulta DeepSeek V4.

Para la configuración de primera clase de MiniMax, endpoints regionales y los IDs de modelo compatibles MiniMax-M3 y MiniMax-M2.7, consulta MiniMax.

CLI

managed-agents init
managed-agents start [--host 127.0.0.1] [--port 3000]
managed-agents list
managed-agents reload
managed-agents chat <agent-id> --message "hello"
managed-agents template list | install <name> | create <name>

Ejemplos de API

Crea un agente:

curl -X POST http://127.0.0.1:3000/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Incident commander",
    "model": "gpt-4o",
    "system": "You are an on-call incident commander.",
    "tools": [{ "type": "agent_toolset_20260401" }]
  }'

Crea un entorno (sandbox local):

curl -X POST http://127.0.0.1:3000/v1/environments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default local",
    "config": { "hosting_type": "local", "sandbox_provider": "local" }
  }'

Crea un entorno aislado con Docker:

curl -X POST http://127.0.0.1:3000/v1/environments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docker sandbox",
    "config": {
      "sandbox_provider": "docker",
      "image": "node:22-slim",
      "resources": { "memory": "1g", "cpu": 1 }
    }
  }'

Inicia una sesión:

curl -X POST http://127.0.0.1:3000/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_...",
    "environment_id": "env_...",
    "title": "Triage SENTRY-123"
  }'

Envía un mensaje:

curl -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{ "content": "Investigate the alert." }'

Reanuda el flujo de eventos:

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: 42"

SDK

import { ManagedAgentsClient } from 'managed-agents/sdk';

const client = new ManagedAgentsClient({
  baseUrl: 'http://127.0.0.1:3000',
});

const session = await client.sessions.create({
  agent: 'agent_...',
  environment_id: 'env_...',
});

for await (const event of client.sessions.chat(session.id, 'Hello')) {
  if (event.type === 'agent.message_chunk') {
    process.stdout.write(event.delta ?? '');
  }
}

La API /v1 sigue las formas de recursos de Claude Managed Agents, por lo que también puedes apuntar el SDK de Anthropic al runtime local:

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
  baseURL: 'http://127.0.0.1:3000',
});

const session = await client.beta.sessions.create({
  agent: 'agent_...',
  environment_id: 'env_...',
});

Autenticación

Abierta por defecto. La autenticación se activa cuando existe al menos una clave API:

# Static key via environment
export MANAGED_AGENTS_API_KEY=sk-local-example

# Or create a managed key
curl -X POST http://127.0.0.1:3000/v1/api-keys \
  -H "Content-Type: application/json" \
  -d '{ "name": "Local Console" }'

Los clientes envían Authorization: Bearer <key>.

Definición de agente

Los agentes son archivos YAML en agents/:

name: Incident commander
description: Triages alerts and coordinates response.
model: gpt-4o
system: |-
  You are an on-call incident commander.
mcp_servers:
  - name: sentry
    type: url
    url: https://mcp.sentry.dev/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy: { type: always_ask }
    configs:
      - name: bash
        permission_policy: { type: always_ask }
  - type: mcp_toolset
    mcp_server_name: sentry
skills:
  - type: custom
    skill_id: skill_...
metadata:
  template: incident-commander

Desarrollo

npm ci
npm run typecheck    # src + tests
npm test             # vitest
npm run build        # runtime + console + SDK
npm run release:check  # full local release gate

release:check ejecuta typecheck, pruebas, ambas compilaciones, npm pack --dry-run, smoke de init de CLI y smoke de inicio de examples/basic.

Ecosistema SandBase

  • SandBase Skills — 88 Agent Skills instalables para flujos de trabajo de investigación, inteligencia social, marketing y negocios en Codex, Claude Code, Cursor, Gemini CLI y otros clientes.
  • SandBase CLI — conecta Cursor, Claude Code, Codex, Windsurf, Gemini CLI, OpenCode y otros clientes MCP a más de 2,000 modelos de IA y APIs con un solo comando de incorporación.
  • DSH Plugin Store — descubre, filtra, instala y administra plugins comunitarios de DeepSeek Harness desde la experiencia nativa de Configuración.
  • SandBase — infraestructura de agentes alojada, acceso a modelos, herramientas y sandboxes administrados.

Documentación

Guías de la comunidad

  • Construye un Agente de Investigación Auditable — una guía reproducible que combina libros de evidencia, ejecución en sandbox, credenciales, auditoría y reproducción con SandBase Harness.
  • Autoaloja el runtime de agente de SandBase por SSD Nodes — un recorrido independiente de VPS que cubre instalación, configuración de agentes, servidores MCP, modos de sandbox e implementación con proxy inverso. El artículo demuestra v0.3.2; usa el comando de publicación actual anterior para v0.3.8.

Licencia

Apache-2.0