6 métodos para implantar o DeepSeek Harness localmente

TLDR DeepSeek Harness (dsh) é o runtime de agentes open-source da DeepSeek AI, lançado em prévia para desenvolvedores por volta de 13 de agosto de 2026 sob a licença MIT. Ele segue o princípio “Modelo + Harness = Agente”, com cada capacidade (modelos, ferramentas, sessões, sandboxes, loops, UI) implementada como plugins Cordis intercambiáveis.

A forma mais rápida de executá-lo localmente é npx @deepseek-ai/dsh web (requer Node.js ^22.19 ou ≥24), que inicia uma Web UI em http://127.0.0.1:3080. Você fornece uma chave de API da DeepSeek (ou compatível com OpenAI) e um workspace. Builds a partir do código-fonte, apps desktop, Docker, SDK Python e integrações com Ollama também estão disponíveis. Para acesso multi‑modelo de nível de produção, confiabilidade e controle de custos ao usar o harness, direcione as requisições pelo endpoint unificado compatível com OpenAI da CometAPI.

Principais pontos

• DeepSeek Harness não é um modelo — é o runtime/orquestrador local que permite que modelos atuem sobre arquivos, shells, ferramentas e sessões.
• One‑liner oficial: npx @deepseek-ai/dsh web → abre a Web UI local na porta 3080.
• A exigência de Node.js é rígida: ^22.19.0 ou ≥24.x.
• Suporta modelos oficiais DeepSeek (deepseek-v4-flash, deepseek-v4-pro), gateways personalizados compatíveis com OpenAI e modelos locais via plugins/Ollama.
• A arquitetura é totalmente baseada em plugins (kernel Cordis); os modos incluem Standard, Minimal, Code e Creator.
• Adoção rápida: dezenas de milhares a bem mais de 100k 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 personalizado 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.
• O status de developer preview significa que são esperadas mudanças incompatíveis — fixe versões para experimentos com perfil de produção.

O que é o DeepSeek Harness e por que importa em 2026

DeepSeek Harness (dsh) é um runtime de agentes open-source desenvolvido pela DeepSeek AI. Lançado sob a licença MIT em developer preview, enfatiza a componibilidade: cada capacidade — adaptadores de modelos, ferramentas, habilidades, sessões, sandboxes, armazenamento, loops de agente, agendamento e a UI — existe como um plugin Cordis que pode ser montado, desmontado, trocado ou recomposto via configuração. Na prática, não há um núcleo privilegiado que exija aplicação de patches.

Princípios de design-chave incluem:

• Agente = Modelo + Harness.
• Fluxos de eventos rastreáveis com suporte a retomar, bifurcar, pesquisar e reproduzir.
• Múltiplos modos de runtime (conjunto completo de ferramentas padrão, modo de código/orquestração, modo minimal para benchmarking, modos creator/experimentais).
• Web UI local-first para uso interativo, além de opções headless e SDK para automação.

Recursos oficiais:

• GitHub: https://github.com/deepseek-ai/deepseek-harness
• 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 principais.

Observação importante de terminologia: “implantação local” pode significar duas coisas. O DeepSeek Harness discutido neste guia é executado localmente no seu computador, mas o projeto padrão deepseek-harness conecta-se a DeepSeek V4-Pro ou V4-Flash por meio de uma 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ê precisar 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 do 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. A faixa alvo é ^22.19.0 || >=24.0.0. Verifique com node --version. Versões intermediárias ímpares fora dessa faixa não são suportadas.
• Gerenciadores de pacotes: npm/npx (vem com o Node). Builds a partir do código exigem 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 em platform.deepseek.com, ou qualquer endpoint compatível com OpenAI + chave + nome do modelo.
• Hardware: Não é necessária GPU para o próprio harness — a inferência do modelo ocorre remotamente (ou via um provedor local que você configurar). Recursos comuns de laptop 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 as chamadas da API do modelo.
• Workspace: Prepare um diretório isolado. O agente pode ler, escrever e executar comandos dentro do workspace configurado — nunca aponte para dados de produção ou pessoais sem proteções.

Fontes para requisitos: README oficial e vários 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 promovido oficialmente.

1. Garanta que o Node.js atenda ao requisito de versão.
2. Abra um terminal e execute:

Bash

npx @deepseek-ai/dsh web

1. O pacote é baixado (ou usa o cache), inicia o perfil da Web UI e imprime o endereço de escuta — por padrão http://127.0.0.1:3080.
2. Abra essa URL em um navegador. Aceite o aviso de developer preview se exibido.
3. 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.
4. Escolha ou crie um diretório de workspace.
5. 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: Nenhuma 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 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 personalizados 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 (sem configuração de Node)

Wrappers desktop da comunidade 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 empacotado e sincronizam o harness upstream mais recente na inicialização. Eles rodam em 127.0.0.1:3080, mantêm os dados locais e registram comandos dsh.
• Empacotamento baseado em Electron com dependências fixadas.

Baixe instaladores nas respectivas páginas de Releases do 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 os checksums SHA.

Método 4: Implantação com Docker/containers

Existem imagens Docker e arquivos compose da comunidade para executar a Web UI dentro de um container, geralmente 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   # set API key / public host
docker compose up -d --build

Útil para acesso via LAN, servidores ou ambientes nos quais o Node não é desejado no host. Alguns setups suportam um settings.yaml personalizado 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 inclusos ou use a classe DeepSeekHarness no seu próprio código com um workspace e diretório de sessão isolados. 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 de conveniência:

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. Pesquisa na Web e suporte a ferramentas dependem do modelo escolhido e do acesso cloud 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 personalizados/autohospedados/agregadores: escolha “Add a custom provider”. Forneça um ID de Provedor permanente, a base URL, o protocolo (geralmente openai-completions), a 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 perfil 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) por meio de um endpoint único compatível com OpenAI: https://api.cometapi.com/v1.

Benefícios ao usar com o DeepSeek Harness:

• Uma única chave de API em vez de gerenciar múltiplas credenciais de provedores.
• Preços competitivos (relatados 20–40% mais baixos do que tarifas diretas de muitos fornecedores).
• Alta disponibilidade (meta de SLA 99,9%), baixa latência mediana e faturamento pay‑as‑you‑go.
• Troca fácil de modelos para A/B testing ou otimização de custos sem mudar a configuração do harness além do ID do modelo.
• Compatibilidade plug‑and‑play: padrões existentes do SDK OpenAI funcionam após trocar apenas base_url e a chave.

No formulário de provedor personalizado do 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 pelo catálogo da CometAPI

Essa combinação mantém o poderoso runtime de agente local ao mesmo tempo em que oferece acesso multi‑fornecedor flexível e econômico. 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 mostra apenas descritores redigidos.

Solução de problemas do DeepSeek Harness

DEEPSEEK_API_KEY não encontrada

Verifique:

echo $DEEPSEEK_API_KEY

No Windows:

echo $env:DEEPSEEK_API_KEY

Se vazio, configure novamente.

Erro 400 reasoning_content

Geralmente aponta para tratamento incorreto do ciclo de raciocínio.

Verifique se sua aplicação preserva as informações relevantes de raciocínio do assistente em requisições multi‑turn de thinking/tool‑call.

Este é um dos problemas centrais que o harness foi especificamente projetado para lidar.

Erro de limite de contexto

Verifique:

input tokens + max_tokens

O teto rígido documentado é:

1,048,576 tokens

Reduza o contexto de entrada ou o tamanho de conclusão solicitado.

Chamadas de ferramenta ficam malformadas durante streaming

Não presuma que os chunks de stream chegam na ordem das ferramentas.

Agregue os deltas de chamadas de ferramenta por tool_call.index, conforme recomendado pelo contrato do harness.

As requisições estão inesperadamente caras

Verifique:

• modo de raciocínio
• tamanho da saída
• taxa de acertos em cache
• estabilidade do prefixo do prompt
• escolha do modelo
• preços atuais da API

Uma melhoria simples muitas vezes é mover tarefas rotineiras do Pro para o Flash.

Comparação dos métodos de instalação e implantação

Dados sintetizados a partir da documentação oficial e guias pós‑lançamento (agosto de 2026).

Conclusão e próximos passos

DeepSeek Harness traz um runtime de agente totalmente baseado em plugins para máquinas locais com praticamente zero atrito via o one‑liner npx. Com roteamento de modelos flexível — especialmente por meio de uma plataforma unificada como a CometAPI — você obtém tanto o poder dos fluxos de trabalho de codificação agentic modernos quanto o 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 da CometAPI, aponte para um workspace seguro e explore o modo Standard. Depois, experimente o modo Minimal para benchmarks, provedores personalizados para otimização de custos ou o SDK Python para automação.

Para as instruções oficiais mais recentes, prefira sempre o repositório do GitHub e a documentação. Para confiabilidade multi‑modelo e vantagens de preço ao executar o harness, explore a CometAPI e sua documentação em https://apidoc.cometapi.com/.