TLDR DeepSeek Harness (dsh) é o runtime de agente de código aberto da DeepSeek AI, lançado em developer preview por volta de 13 de agosto de 2026 sob a licença MIT. Segue o princípio “Model + Harness = Agent”, com cada capacidade (modelos, ferramentas, sessões, sandboxes, loops, UI) implementada como plugins Cordis intercambiáveis.
A forma mais rápida de executar localmente é npx @deepseek-ai/dsh web (requer Node.js ^22.19 ou ≥24), o que inicia uma Web UI em http://127.0.0.1:3080. Você fornece uma chave de API DeepSeek (ou compatível com OpenAI) e um workspace. Compilações a partir do código-fonte, apps desktop, Docker, SDK Python e integrações com Ollama também estão disponíveis. Para acesso a múltiplos modelos em nível de produção, confiabilidade e controle de custo ao usar o harness, encaminhe as requisições pelo endpoint unificado compatível com OpenAI do CometAPI.
Principais Pontos
- DeepSeek Harness não é um modelo — é o runtime/orquestrador local que permite aos modelos agir sobre arquivos, shells, ferramentas e sessões.
- One-liner oficial:
npx @deepseek-ai/dsh web→ abre a Web UI local na porta 3080. - Requisito de Node.js é estrito: ^22.19.0 ou ≥24.x.
- Suporta modelos oficiais da DeepSeek (deepseek-v4-flash, deepseek-v4-pro), gateways customizados compatíveis com OpenAI e modelos locais via plugins/Ollama.
- Arquitetura totalmente baseada em plugins (núcleo Cordis); modos incluem Standard, Minimal, Code e Creator.
- Adoção rápida: dezenas de milhares até mais de 100 mil estrelas no GitHub em poucos dias após o lançamento.
- Recomendado para usuários avançados: combine com CometAPI (https://www.cometapi.com/) como provedor customizado para acesso a 500+ modelos, economia de 20–40% e uma única chave de API.
- Sempre use um workspace isolado; o agente pode modificar arquivos e executar comandos.
- Status de developer preview implica mudanças incompatíveis — fixe versões para experimentos com características de produção.
O que é o DeepSeek Harness e por que importa em 2026
DeepSeek Harness (dsh) é um runtime de agente open-source desenvolvido pela DeepSeek AI. Lançado sob a licença MIT em developer preview, enfatiza a componibilidade: toda capacidade — adaptadores de modelo, ferramentas, habilidades, sessões, sandboxes, storage, loops de agente, agendamento e a UI — existe como um plugin Cordis que pode ser montado, desmontado, trocado ou recomposto via configuração. Praticamente não há um núcleo privilegiado que exija patches.
Princípios de design-chave incluem:
- Agent = Model + Harness.
- Fluxos de eventos rastreáveis com suporte a retomar, bifurcar, buscar e reproduzir.
- Múltiplos modos de runtime (conjunto de ferramentas completo padrão, modo de código/orquestração, modo mínimo para benchmarking, modos creator/experimentais).
- Web UI local para uso interativo, além de opções headless e SDK para automação.
Recursos oficiais:
- GitHub: https://github.com/deepseek-ai/deepseek-harness
- Página do produto/landing: https://www.deepseek.com/harness/en/ (e versão em chinês)
- Páginas de instalação e espelhos da comunidade reforçam os mesmos comandos centrais.
Nota importante de terminologia: “implantação local” pode significar duas coisas diferentes. O DeepSeek Harness discutido neste guia roda localmente no seu computador, mas o projeto padrão
deepseek-harnessconecta-se a DeepSeek V4-Pro ou V4-Flash via API. Isso significa que o harness, a configuração, as sessões, a validação e a lógica do cliente podem ser locais, enquanto a inferência do modelo normalmente é realizada pela API da DeepSeek. Se você precisa de inferência realmente offline com pesos do modelo na sua própria GPU, trata-se de uma arquitetura de implantação diferente.
Pré-requisitos e requisitos de sistema
Antes de instalar, verifique o seguinte:
- Sistemas operacionais: Windows 10+, macOS 10.15+, Linux mainstream (x64 ou arm64). O SDK Python tem restrições adicionais (Linux x64/arm64 ou macOS 14+ arm64).
- Node.js: Necessário para o caminho principal da Web UI. Faixa alvo é ^22.19.0 || ≥24.0.0. Verifique com node --version. Versões intermediárias ímpares fora desse intervalo não são suportadas.
- Gerenciadores de pacotes: npm/npx (vem com Node). Compilações a partir do código-fonte precisam de pnpm (instale via npm install -g pnpm).
- Git: Necessário para clonar o código-fonte.
- Python (opcional): 3.10+ para o SDK Python oficial.
- Chave de API / endpoint: Uma chave de API da DeepSeek de platform.deepseek.com, ou qualquer endpoint compatível com OpenAI + chave + nome de modelo.
- Hardware: Não é necessária GPU para o próprio harness — a inferência do modelo acontece remotamente (ou via um provedor local que você configurar). Recursos de um laptop comum são suficientes para a Web UI e a orquestração.
- Rede: Necessária na primeira execução para buscar pacotes; depois, a UI pode operar apenas com chamadas à API do modelo.
- Workspace: Prepare um diretório isolado. O agente pode ler, escrever e executar comandos dentro do workspace configurado — nunca o aponte para dados de produção ou pessoais sem salvaguardas.
Fontes para requisitos: README oficial e múltiplos guias de instalação independentes publicados logo após o lançamento.
Método 1: One-liner oficial com npx (recomendado para a maioria dos usuários)
Este é o caminho mais rápido e oficialmente promovido.
- Garanta que o Node.js atende ao requisito de versão.
- Abra um terminal e execute:
Bash
npx @deepseek-ai/dsh web
- O pacote é baixado (ou usa cache), inicia o perfil da Web UI e imprime o endereço de escuta — por padrão http://127.0.0.1:3080.
- Abra essa URL no navegador. Aceite o aviso de developer preview, se for exibido.
- No primeiro uso, configure um provedor de modelo (Settings → Models) colando sua chave de API e selecionando um modelo como deepseek-v4-flash ou deepseek-v4-pro.
- Escolha ou crie um diretório de workspace.
- Comece a emitir tarefas.
Para usar uma porta diferente:
Bash
npx @deepseek-ai/dsh web --port 8080
One-liners específicos da plataforma que também garantem a presença do Node estão disponíveis em sites da comunidade (PowerShell no Windows com winget, Homebrew no macOS, NodeSource no Debian/Ubuntu, etc.).
Prós: Zero pegada de instalação permanente além do cache do npm; sempre obtém uma versão publicada recente; onboarding mais simples. Contras: Depende de rede para o pacote inicial; menos conveniente para inspeção profunda do código-fonte ou builds personalizados.
Método 2: Instalar e executar a partir do código-fonte
Use quando quiser ler plugins Cordis, fixar um commit, desenvolver presets customizados ou contribuir.
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
A mesma Web UI aparece na porta padrão. Builds em developer preview podem quebrar entre commits, então trate este caminho como experimental.
Método 3: Aplicativos desktop (zero configuração de Node)
Wrappers desktop comunitários e de terceiros empacotam o runtime para que os usuários evitem instalar Node/pnpm:
- Clientes leves baseados em Tauri que inicializam um runtime Node incluído e sincronizam o harness upstream mais recente ao iniciar. Eles rodam em 127.0.0.1:3080, mantêm dados locais e registram comandos dsh.
- Empacotamento baseado em Electron que inclui dependências fixadas.
Baixe os instaladores nas respectivas páginas de Releases no GitHub (procure “deepseek-harness-desktop”). A primeira execução baixa os componentes centrais (algumas centenas de MB). São convenientes para não desenvolvedores, mas não são produtos oficiais da DeepSeek — revise o repositório e checksums SHA.
Método 4: Implantação com Docker / container
Imagens Docker e arquivos compose da comunidade existem para executar a Web UI dentro de um container, frequentemente com terminação HTTPS via nginx e suporte a gateways arbitrários compatíveis com OpenAI. Fluxo típico:
Bash
git clone <docker-repo>
cd <docker-repo>
cp .env.example .env # defina a chave de API / host público
docker compose up -d --build
Útil para acesso em LAN, servidores ou ambientes onde não se deseja Node no host. Alguns setups suportam settings.yaml custom para provedores não-DeepSeek.
Método 5: SDK Python para uso programático / headless
Para agentes sem supervisão ou integração em pipelines Python:
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk
Defina variáveis de ambiente:
Bash
export DEEPSEEK_API_KEY=sk-your-key-here
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: export DSH_MODEL=deepseek-v4-flash
Em seguida, execute os exemplos incluídos ou use a classe DeepSeekHarness no seu próprio código com um workspace isolado e diretório de sessões. O SDK inclui seu próprio runtime e não requer Node.js no sistema.
Método 6: Integração com Ollama
Ollama fornece um lançador conveniente:
Bash
ollama launch dsh
# or with a specific model
ollama launch dsh --model deepseek-v4-flash:cloud
O Ollama pode instalar o pacote se necessário e armazena as configurações de lançamento separadamente. Busca na web e suporte a ferramentas dependem do modelo escolhido e do acesso à nuvem do Ollama.
Configurando modelos e provedores (incluindo CometAPI)
Dentro da Web UI, vá para Settings → Models.
- Para a DeepSeek oficial: cole a chave de platform.deepseek.com. Modelos típicos são deepseek-v4-flash e deepseek-v4-pro.
- Para provedores de catálogo (Anthropic, OpenAI, etc.): use o fluxo “Add provider”.
- Para endpoints customizados / auto-hospedados / agregadores: escolha “Add a custom provider”. Forneça um Provider ID permanente, base URL, protocolo (geralmente openai-completions), referência de variável de ambiente da chave de API ou valor, e pelo menos um ID de modelo.
Recomendação CometAPI (fortemente sugerida para muitos fluxos de trabalho com características de produção) CometAPI é uma plataforma unificada de infraestrutura de IA que expõe 500+ modelos (incluindo variantes DeepSeek, GPT, Claude, Gemini, Grok e muitos outros) através de um endpoint único compatível com OpenAI: https://api.cometapi.com/v1.
Benefícios quando usado com DeepSeek Harness:
- Uma única chave de API em vez de gerenciar várias credenciais de provedores.
- Preços competitivos (reportados 20–40% de economia em relação a tarifas diretas de muitos fornecedores).
- Alta disponibilidade (meta de SLA 99,9%), baixa latência mediana e cobrança pay-as-you-go.
- Troca fácil de modelo para A/B testing ou otimização de custo sem mudar a configuração do harness além do ID do modelo.
- Compatibilidade plug-and-play: padrões existentes do SDK OpenAI funcionam alterando apenas base_url e a chave.
No formulário de provedor custom no harness:
- Base URL:
https://api.cometapi.com/v1 - Protocolo: openai-completions (ou a opção equivalente suportada)
- Chave de API: sua chave CometAPI
- ID do modelo: qualquer string de modelo suportada no catálogo de modelos do CometAPI
Essa combinação mantém o potente runtime de agente local oferecendo acesso a modelos flexível, econômico e multi-fornecedor. Novos usuários normalmente recebem créditos de teste gratuitos. Documentação: https://apidoc.cometapi.com/.
As chaves são armazenadas como write-only (por exemplo, em $DSH_HOME/.credentials.yaml); a UI exibe apenas descritores redigidos.
Solução de problemas do DeepSeek Harness
DEEPSEEK_API_KEY não encontrado
Verifique:
echo $DEEPSEEK_API_KEY
No Windows:
echo $env:DEEPSEEK_API_KEY
Se estiver vazio, configure novamente.
Erro 400 reasoning_content
Geralmente indica tratamento incorreto do ciclo de vida do raciocínio.
Verifique se sua aplicação preserva as informações relevantes de raciocínio do assistant em requisições multi-turn de thinking/tool-call.
Esse é um dos problemas centrais que o harness foi especificamente projetado para lidar.
Erro de comprimento de contexto
Verifique:
input tokens + max_tokens
O teto documentado é:
1,048,576 tokens
Reduza o contexto de entrada ou o tamanho de completion solicitado.
Chamadas de ferramenta se tornam malformadas durante streaming
Não presuma que os chunks de stream chegam na ordem das ferramentas.
Agregue deltas de tool-call por tool_call.index, conforme recomendado pelo contrato do harness.
Requisições inesperadamente caras
Verifique:
- modo de thinking
- comprimento do output
- taxa de acerto do cache
- estabilidade do prefixo de prompt
- escolha do modelo
- preços atuais da API
Uma melhoria simples é mover tarefas rotineiras de Pro para Flash.
Comparação dos métodos de instalação e implantação
| Método | Facilidade de uso | Node necessário | Melhor para | Persistência / controle | Porta / acesso típico | Observações |
|---|---|---|---|---|---|---|
| npx one-liner | Maior | Sim | Testes rápidos, maioria dos usuários | Efêmero (apenas cache) | 3080 (configurável) | Recomendação oficial |
| Código-fonte (pnpm) | Média | Sim | Desenvolvimento, plugins, pinning | Controle total do código-fonte | 3080 | Requer pnpm + build |
| Desktop (Tauri/Electron) | Alta | Não (incluso) | Usuários não técnicos | Perfis locais e auto-update | 3080 (interno) | Pacotes da comunidade |
| Docker | Média | Não (container) | Servidores, LAN, HTTPS | Volumes do container | Personalizada / 443 | Imagens da comunidade |
| SDK Python | Média | Não (incluso) | Headless, automação, pipelines | Sessões programáticas | N/A (sem UI por padrão) | SDK oficial |
| Lançamento via Ollama | Alta | Opcional | Experimentos com modelos locais | Configurações do Ollama | 3080 | Integra com Ollama |
Dados sintetizados de docs oficiais e guias pós-lançamento (agosto de 2026).
Conclusão e próximos passos
DeepSeek Harness traz um runtime de agente de design limpo e totalmente baseado em plugins para máquinas locais, com praticamente zero atrito via o one-liner npx. Com o roteamento flexível de modelos — especialmente através de uma plataforma unificada como o CometAPI — você obtém tanto o poder de fluxos de trabalho de coding agentic modernos quanto controle prático sobre custo, escolha de modelo e localidade dos dados.
Comece hoje com:
npx @deepseek-ai/dsh web
Configure uma chave da DeepSeek ou do CometAPI, aponte para um workspace seguro e explore o modo Standard. Depois, experimente o modo Minimal para benchmarks, provedores customizados para otimização de custos ou o SDK Python para automação.
Para as instruções oficiais mais recentes, prefira sempre o repositório no GitHub e a doc. Para confiabilidade multi-modelo e vantagens de preço enquanto executa o harness, explore o CometAPI e sua documentação em https://apidoc.cometapi.com/.


