SandBase Harness

Runtime auto-hospedado local-first e ponte stdio MCP para sessões auditáveis de agentes de IA.

GitHub
643
Experimente este MCPPatrocinado

Documentação

SandBase Harness

English | 中文

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

Metadados de projeto legíveis por IA: llms.txt · guia de instalação

Um runtime local-first para agentes de IA. Sessões, ferramentas em sandbox, memória, credenciais, trilhas de auditoria e um Console integrado — tudo rodando na sua máquina ou na sua própria infraestrutura.

Construindo com DeepSeek Harness? O Manual do DeepSeek Harness independente fornece guias de runtime com base no código-fonte, solução de problemas multilíngue e um mapa de recursos agent-first atualizado regularmente.

SandBase Harness architecture

Procurando uma ponte leve em vez de um runtime completo? O SandBase CLI conecta 25 alvos de clientes de IA a mais de 2.000 modelos e APIs por meio de uma ponte MCP stdio local. Se isso se encaixa no seu fluxo de trabalho, dê uma estrela ao SandBase CLI para que outros usuários de agentes possam descobri-lo.

Precisa de APIs hospedadas de modelos e mídia? O SandBase fornece uma interface única para APIs de geração de LLM, imagem e vídeo, com o início rápido de API cobrindo chaves e primeiras chamadas.

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

Escolha o SandBase Harness quando você precisar de mais do que um loop de modelo:

NecessidadeO que o Harness oferece
Executar código gerado com segurançaSandboxes de worker locais, Docker, Kubernetes e auto-hospedados
Inspecionar agentes de longa duraçãoSessões persistentes, fluxos de eventos retomáveis, auditoria e replay
Controlar acesso a ferramentasConjuntos de ferramentas MCP, cofres de credenciais, políticas de permissão e aprovações
Operar qualquer modeloOpenAI, Anthropic, MiniMax e provedores compatíveis com OpenAI, incluindo DeepSeek V4
Manter sua infraestrutura suaArmazenamento local-first em SQLite e arquivos, sem plano de controle hospedado obrigatório

Se este runtime resolve um problema real de infraestrutura de agentes para você, de uma estrela ao repositório para que outros construtores possam encontrá-lo.

Encontre o SandBase Harness

O projeto também é descobrível por meio destes diretórios independentes do ecossistema:

Referências comunitárias verificadas recentemente:

Revisão comunitária pendente:

Experimente no Codespaces

Open in GitHub Codespaces

O container de desenvolvimento incluído instala dependências e compila o runtime. Quando o terminal estiver pronto, inicie o servidor na porta encaminhada:

node dist/index.js start --host 0.0.0.0

Abra a porta encaminhada do SandBase Harness Console e configure um modelo em Settings > Models. O uso do Codespaces pode ser cobrado pelo GitHub; o quick start local abaixo permanece gratuito e mantém todos os dados do runtime na sua máquina.

Por quê

Os SDKs de agentes lidam com o loop do modelo. Agentes de produção precisam de mais: sessões persistentes, governança de ferramentas, limites de sandbox, tratamento de credenciais, memória, auditabilidade e uma interface para humanos inspecionarem o que aconteceu. managed-agents é essa camada de runtime — não um construtor visual de fluxos de trabalho e nem outro SDK de modelos.

Recursos

  • API /v1 estilo Claude Managed Agents e Console local
  • Agentes, sessões, ambientes, cofres de credenciais, armazenamentos de memória, arquivos, skills e chaves de API com suporte a SQLite — metadados SQLite por padrão
  • Bytes locais de arquivos/skills armazenados no diretório de estado do workspace
  • Server-Sent Events retomáveis para replay e depuração de sessões
  • Um limite ativo de provedor de modelo configurado por meio do Settings V2
  • Backends de sandbox: processo local, Docker (containers por sessão), Kubernetes (kubectl exec/cp), fila de workers auto-hospedada
  • Settings V2: um fornecedor de modelo do workspace, mecanismo de loop, armazenamento, memória, sandbox — com validação, modos de formulário/JSON e fluxo de reinicialização
  • Conjuntos de ferramentas MCP, políticas de permissão, ferramentas integradas e pacotes de skills
  • Ponte DeepSeek Harness sobre MCP stdio para agentes, sessões, turnos transmitidos, artefatos e cancelamento
  • SDK TypeScript em managed-agents/sdk
  • Portão de release: npm run release:check

Capturas de tela

Visão geral do ConsoleConfiguraçõesReferência da API
overviewsettingsapi-ref

Comece com um caso de uso

Veja o Showcase para três caminhos práticos: um agente de codificação auditável, DeepSeek Harness como front-end interativo e execução de código controlada em sandboxes Local, Docker, Kubernetes e auto-hospedados.

Para configuração específica de cliente, veja o guia de instalação, incluindo o comando Cline CLI fixado e a configuração do Docker MCP Bridge.

Discussões de casos de uso da comunidade:

Requisitos

  • Node.js 22+
  • npm 10+
  • Uma chave de API do provedor de modelo (OpenAI, Anthropic, MiniMax ou um endpoint compatível com OpenAI)
  • Docker (opcional, para sandboxes com suporte a Docker)

DeepSeek Harness

Execute este projeto como um plugin DSH em vez de tratar dsh-plugin apenas como metadados de descoberta. Instale o bundle em um perfil DSH, inicie managed-agents, e então inicialize esse 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

Se o Plugin Hub relatar already installed: managed-agents após uma instalação parcial ou repetida, atualize o Hub primeiro, depois remova apenas a entrada de plugin managed-agents exibida e tente novamente a partir da fonte Git HTTPS marcada:

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

Este é um caminho de instalação duplicada do Plugin Hub, não um caminho de instalação npm. Se a visualização instalada mostrar um identificador de destino diferente, remova exatamente esse identificador. Mantenha o diretório do perfil e suas evidências até que o runtime inicie com sucesso; veja o problema de recuperação relatado.

O perfil instala o checkout da fonte verificada diretamente; ele não resolve o pacote npm não relacionado sem escopo. Uma instalação hospedada em git executa prepare apenas quando dist/ estiver ausente. Mantenha a especificação git HTTPS; convertê-la para SSH falha em hosts Windows sem acesso SSH ao GitHub.

Uma instalação hospedada em git precisa de uma etapa extra para a lista de permissões de build do pnpm. O primeiro dsh plugin --profile web add falha com ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED e imprime a chave exata. Adicione essa chave em allowBuilds: no pnpm-workspace.yaml do perfil e execute novamente o mesmo comando add; um nome de pacote simples não corresponde a uma resolução hospedada em git:

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

A segunda execução compila dist/ por meio de prepare, cria os bins managed-agents / managed-agents-mcp e junta a camada do bundle. O patch inicia a entrada MCP empacotada via stdio. O DSH pode então listar agentes, criar e executar sessões, inspecionar resultados e artefatos e interromper o trabalho por meio de ferramentas nativas mcp__sandbase__*. Veja examples/deepseek-harness para a lista completa de ferramentas e configuração de runtime autenticado.

Para um passo a passo que começa com DSH e adiciona este runtime como um plugin real de terceiros, leia o guia do desenvolvedor DeepSeek Harness. A edição em chinês também está disponível; ambos os artigos são mantidos contra a integração fixada SandBase Harness v0.3.8.

Combine o plugin com SandBase Skills para dar ao mesmo projeto DSH um fluxo de trabalho de pesquisa portátil e verificável por fonte:

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

Isso instala a Skill completa em .dsh/skills/multi-source-search, o diretório de descoberta com escopo de projeto do DSH. Ele é executado a partir da fonte do GitHub e não precisa de conta SandBase quando o DSH já fornece ferramentas web/busca.

Para um fluxo de trabalho completo e reproduzível que combina o registro de evidências com execução em sandbox, credenciais, auditoria e replay, leia Build an Auditable Research Agent.

Novo em perfis DSH, composição de plugins, política de ferramentas ou semântica de sessão? O DeepSeek Harness Handbook independente fornece quickstarts com suporte de fonte, mapas de arquitetura e solução de problemas para as camadas de runtime usadas por esta integração. Leia seu guia de ponte SandBase Harness para o contrato específico do DSH e comece com o Install Doctor no navegador local para evidências de instalação, ou use o Failure Router para identificar o primeiro limite de runtime quebrado.

Quick Start

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

Abra http://127.0.0.1:3000/dashboard, vá para Settings > Models, cole sua chave de API e você está rodando.

O nome managed-agents sem escopo no npm não é este projeto. Até que um pacote oficial com escopo seja anunciado neste repositório, instale apenas a partir da release de fonte GitHub marcada mostrada acima. Não execute npx managed-agents ou npm install managed-agents.

A ponte MCP de seis ferramentas é publicada como uma imagem OCI multi-arquitetura. Inicie a API Harness e adicione este comando stdio a um cliente MCP:

Pacote de container: GitHub Container Registry

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 um runtime remoto autenticado, passe também MANAGED_AGENTS_API_KEY. A imagem do container contém apenas a ponte MCP; sessões de agente e trabalho em sandbox permanecem no runtime Harness conectado. Cada imagem de release é construída a partir da tag Git correspondente para linux/amd64 e linux/arm64, inclui fonte OCI e metadados de propriedade MCP e recebe uma atestação de proveniência de build do GitHub.

Plugin de Agente Portátil

Copilot CLI, VS Code e outros clientes Agent Plugins 1.0 podem instalar a mesma ponte MCP com suporte OCI diretamente deste repositório. Inicie a API Harness e o Docker primeiro e exponha sua URL ao processo do 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

O plugin passa essas variáveis de ambiente para a imagem ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8 fixada. Ele não armazena uma chave em plugin.json, mcp.json ou nos arquivos do plugin instalado. No Linux, o comando Docker do plugin mapeia host.docker.internal por meio de host-gateway.

Para desenvolvimento a partir do branch main mais recente:

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

Layout do Workspace

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

Configuração

.managed-agents/config.yaml:

model:
  provider: openai
  api_key: ${OPENAI_API_KEY}

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

Os agentes escolhem IDs de modelo concretos (gpt-4o, claude-sonnet-4-20250514, openai/gpt-5.5). A configuração do workspace apenas diz como alcançar o serviço de modelo.

Para configuração do DeepSeek V4 Pro/Flash, incluindo esforço máximo de raciocínio, veja DeepSeek V4.

Para configuração de primeira classe do MiniMax, endpoints regionais e os IDs de modelo suportados MiniMax-M3 e MiniMax-M2.7, veja 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>

Exemplos de API

Crie um 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" }]
  }'

Crie um ambiente (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" }
  }'

Crie um ambiente isolado com 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 }
    }
  }'

Inicie uma sessão:

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"
  }'

Envie uma mensagem:

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

Retome o fluxo 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 ?? '');
  }
}

A API /v1 segue as formas de recurso do Claude Managed Agents, então você também pode apontar o SDK Anthropic para o 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_...',
});

Autenticação

Aberto por padrão. A autenticação é ativada quando pelo menos uma chave de API existe:

# 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" }'

Os clientes enviam Authorization: Bearer <key>.

Definição de Agente

Agentes são arquivos YAML em 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

Desenvolvimento

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 executa typecheck, testes, ambos os builds, npm pack --dry-run, smoke de init da CLI e smoke de inicialização do examples/basic.

Ecossistema SandBase

  • SandBase Skills — 88 Agent Skills instaláveis para fluxos de trabalho de pesquisa, inteligência social, marketing e negócios em Codex, Claude Code, Cursor, Gemini CLI e outros clientes.
  • SandBase CLI — conecte Cursor, Claude Code, Codex, Windsurf, Gemini CLI, OpenCode e outros clientes MCP a mais de 2.000 modelos e APIs de IA com um único comando de onboarding.
  • DSH Plugin Store — descubra, filtre, instale e gerencie plugins comunitários do DeepSeek Harness na experiência nativa de Settings.
  • SandBase — infraestrutura de agente hospedada, acesso a modelos, ferramentas e sandboxes gerenciados.

Documentação

Guias da Comunidade

  • Build an Auditable Research Agent — um guia reproduzível que combina registros de evidências, execução em sandbox, credenciais, auditoria e replay com SandBase Harness.
  • Self-host the SandBase agent runtime por SSD Nodes — um passo a passo independente de VPS cobrindo instalação, configuração de agente, servidores MCP, modos de sandbox e implantação com proxy reverso. O artigo demonstra a v0.3.2; use o comando de release atual acima para a v0.3.8.

Licença

Apache-2.0