Como Instalar o DeepSeek Harness em 10 Minutos (E Apontá-lo para Qualquer Modelo que Você Quiser)

A instalação do DeepSeek Harness leva um único comando. Trinta segundos depois, você está olhando para uma interface bonita e completamente vazia em http://127.0.0.1:3080, e ninguém lhe disse o que fazer a seguir.

O README é notoriamente enxuto. O artigo do Cordis que ele linka fala sobre composabilidade espaço-temporal. Você só queria que a coisa lesse seu código.

Este guia começa nessa tela vazia. Você receberá o comando de instalação, sim, mas a parte que realmente custa uma tarde é conectar um provedor de modelo, e há três valores padrão nessa etapa que silenciosamente quebram modelos DeepSeek e jogam fora 75% da sua janela de contexto. Quase ninguém os documenta.

Principais conclusões

• npx @deepseek-ai/dsh web é a instalação completa. Node.js ^22.19.0 ou >=24.0.0 é o único pré-requisito.
• DeepSeek Harness é um harness, não um modelo. Ele vem com zero credenciais, então não faz nada até que você anexe um provedor.
• Qualquer endpoint compatível com OpenAI funciona, incluindo a própria API da DeepSeek, um gateway, ou um servidor local Ollama.
• Ao adicionar um provedor personalizado, o harness adivinha o dialeto de pensamento a partir da sua URL base. Errar a adivinhação quebra reasoning_content.
• Modelos declarados manualmente usam como padrão uma janela de contexto de 262.144, então a janela completa de 1.048.576 do V4 permanece desligada até que você diga o contrário.

Terminal mostrando testes verdes passando ao lado de um harness modular brilhante, ilustrando como instalar o DeepSeek Harness

A Versão de 60 Segundos do Que Você Está Construindo

Aqui está a recompensa antes de qualquer teoria. Três arquivos em uma pasta vazia, um prompt colado, e o agente lê o código, executa pytest, observa dois testes falharem, altera um único caractere e reexecuta até que a suíte esteja verde.

DeepSeek Harness lendo fizzbuzz.py, executando pytest, corrigindo o bug de off-by-one e reexecutando até 3 testes passados

O loop completo: ler, executar, diagnosticar, corrigir, reexecutar. Cada etapa é registrada em um log de sessão somente anexação que você pode reproduzir depois.

Esse é o demo que vamos construir juntos na Etapa 6. Ele é deliberadamente pequeno o suficiente para ser reproduzido em um diretório temporário, e não depende de nenhum repositório externo que possa mudar na próxima semana.

Por Que a Maioria das Tentativas de Instalar o DeepSeek Harness Empaca na Etapa Dois

A instalação é realmente trivial. O empacamento ocorre imediatamente depois, e é uma decisão de design, não um bug: o DeepSeek Harness não vem com chaves, nem provedor padrão, nem modelo embutido.

A DeepSeek tornou o projeto open source em 13 de agosto de 2026 sob a licença MIT, e ele explodiu. Em 17 de agosto de 2026, o repositório tem 144.361 estrelas e 14.689 forks (GitHub, agosto de 2026), o que significa muitas pessoas chegando à mesma tela vazia na mesma semana.

O tópico do Hacker News da semana de lançamento captura a reação dividida. As pessoas amam a transparência: tudo que o modelo vê é registrado em um log de sessão somente anexação, e um comentarista notou que "modelos dos EUA não deixam você ver isso". As reclamações são igualmente consistentes. "O README é bem enxuto além das instruções de instalação", escreveu um desenvolvedor, e o artigo do Cordis recebeu o veredito de que parece "salada de palavras" (Hacker News, agosto de 2026).

Portanto, as quatro coisas que realmente bloqueiam as pessoas são todas pós-instalação:

• Node é muito antigo, então npx falha antes de tudo começar.
• A porta 3080 já está ocupada por outro servidor de desenvolvimento.
• O provedor personalizado retorna 401, ou a lista de modelos vem vazia.
• O modelo conecta, mas a saída de raciocínio chega corrompida, ou arquivos longos estouram a janela de contexto cedo.

As etapas 1 a 5 abaixo visam diretamente essas quatro questões.

Antes de Instalar o DeepSeek Harness: Escolha um Modelo e uma Chave

Responda primeiro: o harness em si é gratuito e local, mas não fará nada útil até que você forneça uma URL base compatível com OpenAI, uma chave e pelo menos um ID de modelo. Decida isso antes de instalar e a configuração completa leva dez minutos.

Tudo acontece em uma única aba do navegador em 127.0.0.1:3080. Você está escolhendo entre três rotas, e todas funcionam.

Tabela B: opções de acesso a modelo que funcionam com o DeepSeek Harness hoje

Duas coisas que vale a pena saber antes de escolher. A API first-party da DeepSeek mudou para faturamento em pico e fora de pico, onde os horários de pico são 01:00 às 04:00 e 06:00 às 10:00 UTC, e fora de pico é exatamente metade do pico (DeepSeek API Docs, agosto de 2026). O preço de entrada com cache hit é extremamente baixo, então uma carga de trabalho que relê o mesmo contexto repetidamente pode ser muito barata na first-party.

Um gateway troca isso por previsibilidade. O Atlas Cloud serve os mesmos modelos DeepSeek com taxa fixa, sem sobretaxa de pico e sem assinatura. É o exemplo que usarei na configuração abaixo porque não precisa de método de pagamento regional. Substitua pela rota que se adequar à sua situação; a forma da configuração é idêntica para todas.

Como Instalar o DeepSeek Harness, Passo a Passo

Existem três maneiras. Escolha uma linha e siga as etapas.

Tabela A: métodos de instalação comparados

Etapa 1: Verifique os Pré-requisitos Antes de Instalar o DeepSeek Harness

A falha mais comum é uma versão do Node que parece recente o suficiente, mas não é. O repositório requer ^22.19.0 || >=24.0.0. Nada na linha 23.x se qualifica em qualquer nível de patch.

bashCopy
1node -v      # deve ser >= 22.19.0 na 22.x, ou >= 24.0.0
2npm -v
3

Se node -v imprimir 22.14 ou 20.x, atualize antes de prosseguir. Você só precisa de pnpm se planeja compilar a partir do código fonte ou criar plugins:

bashCopy
1npm install -g pnpm
2

Etapa 2: Instale o DeepSeek Harness com Um Comando

Esta é a instalação completa. Ele baixa e inicia o perfil web em um único comando.

bashCopy
1npx @deepseek-ai/dsh web
2

Abra http://127.0.0.1:3080. Se essa porta já estiver ocupada, o lançador passa quaisquer flags que não reconhece diretamente para o perfil, então você pode movê-la:

bashCopy
1npx @deepseek-ai/dsh web --port 8080
2

O que você obtém é um shell vazio. Sem provedor, sem modelo, sem chave. Isso é esperado, e é onde a maioria dos guias para.

A interface web do DeepSeek Harness em 127.0.0.1:3080 imediatamente após a instalação, sem provedor ou modelo configurado

Instalação completa e completamente inerte. Tudo daqui em diante é cabeamento.

Etapa 3: Obtenha uma Chave de API para o DeepSeek Harness

Qualquer que seja a rota escolhida na Tabela B, você precisa de uma chave e uma URL base. Para a rota first-party, cadastre-se em platform.deepseek.com e crie uma chave lá. As opções de faturamento variam por região, então verifique se seu método de pagamento é compatível antes de se comprometer.

Para a rota de gateway usada neste tutorial, crie uma chave no painel do Atlas Cloud em Chaves de API, depois exporte-a para que o harness possa lê-la sem armazená-la em um arquivo de configurações:

bashCopy
1export ATLASCLOUD_API_KEY="sk-sua-chave-aqui"
2

A página de Chaves de API do painel do Atlas Cloud com uma chave recém-criada, parcialmente mascarada

Copie a chave uma vez. Ela não será mostrada novamente depois que você sair da página.

Etapa 4: Adicione Seu Provedor de Modelo ao DeepSeek Harness

Na interface, vá em Configurações, depois Modelos e clique em Adicionar um provedor personalizado. O formulário precisa de um ID do provedor, um nome de exibição, uma URL base, um protocolo de API, uma credencial e pelo menos um modelo.

Um aviso que os documentos repetem corretamente: o ID do provedor é permanente. Ele é escrito nas requisições, sessões salvas, padrões de modelo e referências de credenciais. Se você não gostar dele depois, sua única opção é criar um novo provedor e excluir o antigo.

Se a busca de modelos retornar 401, a chave está errada. Se retornar uma lista vazia, o endpoint simplesmente não expõe um índice de modelos, o que é inofensivo: digite o ID do modelo manualmente e prossiga.

O formulário "Adicionar um provedor personalizado" preenchido, com a URL base, protocolo de API e controle "Buscar modelos" marcados

Os três campos que decidem se a próxima etapa funciona: URL base, protocolo e a lista de modelos.

Etapa 5: Os Três Padrões do DeepSeek Harness Que Silenciosamente Quebram Modelos DeepSeek

Esta é a parte que nenhum outro guia de instalação cobre, e é a razão pela qual sua configuração pode parecer conectada, mas se comportar de forma estranha.

A camada LLM do harness infere qual dialeto de pensamento falar a partir da URL do seu endpoint. Os documentos internos são diretos sobre a consequência: "pi-ai adivinha a partir da URL do endpoint; a URL de um gateway privado não diz nada, então um gateway de dialeto DeepSeek seria falado no dialeto OpenAI sem maneira de corrigir." Em termos simples, qualquer URL base que não seja obviamente DeepSeek é tratada como OpenAI, e o tratamento de reasoning_content da DeepSeek dá errado.

A segunda e terceira armadilhas são capacidade. Um modelo declarado manualmente usa defaultContextWindow de 262.144 e defaultMaxTokens de 32.768. O V4 suporta 1.048.576 tokens de contexto, então aceitar o padrão joga fora três quartos dele.

Escreva estas opções no seu arquivo de configurações:

yamlCopy
1# $DSH_HOME/settings.yaml   (padrão é ~/.dsh/settings.yaml)
2llm-pi-ai:
3  providers:
4    atlas:
5      displayName: Atlas Cloud
6      api: openai-completions
7      baseURL: https://api.atlascloud.ai/v1
8      apiKeyEnv: ATLASCLOUD_API_KEY
9      compat:
10        thinkingFormat: deepseek   # 1. parar a adivinhação baseada em URL
11      defaultContextWindow: 1048576  # 2. padrão é apenas 262144
12      defaultMaxTokens: 32768        # 3. aumentar para trabalhos de saída longa
13      models:
14        - id: deepseek-ai/deepseek-v4-flash
15          contextWindow: 1048576
16        - id: deepseek-ai/deepseek-v4-pro
17          contextWindow: 1048576
18

Três coisas para manter em mente. As configurações resolvem primeiro modelo, depois rota, depois a entrada do catálogo instalado, depois a adivinhação derivada da URL, então um valor por modelo sempre vence. Ambos os switches compat, thinkingFormat e supportsReasoningEffort, existem apenas sob openai-completions; colocá-los em outro protocolo e a resolução falha. E este adaptador deliberadamente não cobre Bedrock, Vertex, Azure ou Codex, cujos fluxos de autenticação precisam de mais do que uma chave, um endpoint e cabeçalhos.

Etapa 6: Execute Sua Primeira Tarefa Real no DeepSeek Harness

Agora o demo do início deste artigo. Crie uma pasta vazia e adicione três arquivos.

fizzbuzz.py, contendo um bug de off-by-one:

pythonCopy
1def fizzbuzz(n):
2    out = []
3    for i in range(1, n):
4        if i % 15 == 0:
5            out.append("FizzBuzz")
6        elif i % 3 == 0:
7            out.append("Fizz")
8        elif i % 5 == 0:
9            out.append("Buzz")
10        else:
11            out.append(str(i))
12    return out
13

test_fizzbuzz.py, onde dois dos três testes falham:

pythonCopy
1from fizzbuzz import fizzbuzz
2
3def test_starts_correctly():
4    assert fizzbuzz(5)[:3] == ["1", "2", "Fizz"]
5
6def test_covers_every_number():
7    assert len(fizzbuzz(15)) == 15
8
9def test_fifteen_is_fizzbuzz():
10    assert fizzbuzz(15)[-1] == "FizzBuzz"
11

E requirements.txt:

textCopy
1pytest>=8.0
2

Executar a suíte manualmente primeiro vale a pena, para que você saiba no que o agente está entrando:

textCopy
1.FF                                                                      [100%]
2=================================== FALHAS ====================================
3___________________________ test_covers_every_number ___________________________
4E       AssertionError: assert 14 == 15
5___________________________ test_fifteen_is_fizzbuzz ___________________________
6E       AssertionError: assert '14' == 'FizzBuzz'
7=========================== resumo curto dos testes ============================
82 falharam, 1 passou em 0.01s
9

Defina o modo do agente como Padrão e o modelo como deepseek-ai/deepseek-v4-flash, depois cole este prompt exatamente:

Execute pytest neste workspace. Dois testes falham. Encontre a causa raiz em fizzbuzz.py, corrija-a com a menor alteração possível, depois reexecute o pytest e mostre-me a saída final. Não edite o arquivo de teste.

A correção correta é um caractere: range(1, n) se torna range(1, n + 1), e a suíte reporta 3 passed.

Agora a parte que faz um harness ser diferente de uma janela de chat. Cada execução é registrada em um log de sessão somente anexação, e você pode bifurcá-lo. Volte ao ponto em que o agente leu fizzbuzz.py pela primeira vez e ramifique uma segunda tentativa:

Bifurque esta sessão a partir da etapa em que você leu fizzbuzz.py pela primeira vez. Desta vez, reescreva-a como uma busca baseada em dicionário em vez de corrigir a ramificação if, depois execute pytest novamente.

Bifurcando um log de sessão do DeepSeek Harness para produzir uma segunda implementação baseada em dicionário a partir do mesmo ponto de partida

Um ponto de partida, duas ramificações. Esta é a funcionalidade com a qual a multidão da semana de lançamento realmente se importou.

Etapa 7: Vá para Headless para Scripts e CI

Dois perfis se inicializam no primeiro uso: web e headless. Você tem usado web, e dsh web é apenas um alias para dsh --profile web.

Headless executa uma sessão nova e persistida, imprime a resposta final e sai, que é exatamente a forma que um trabalho de CI deseja:

bashCopy
1dsh --profile headless "Execute os testes e corrija quaisquer falhas. Reporte o diff."
2

Qualquer outro perfil precisa ser criado através de dsh plugin. Os perfis ficam em $DSH_HOME/profiles/<nome>, que por padrão é ~/.dsh/profiles/<nome>.

Saída do terminal de uma execução headless do DeepSeek Harness imprimindo a resposta final e saindo

Modo headless: uma sessão, uma resposta, código de saída para ramificar.

Outras Maneiras de Instalar o DeepSeek Harness

A rota npx cobre a maioria das pessoas. Estas três valem a pena conhecer.

Instalar o DeepSeek Harness a Partir do Código Fonte com pnpm

Se você quiser ler o código, corrigi-lo ou escrever plugins para ele:

bashCopy
1git clone https://github.com/deepseek-ai/deepseek-harness
2cd deepseek-harness
3pnpm install
4pnpm run build
5pnpm dsh web
6

O Build Desktop de 5 MB

Um projeto da comunidade, hairyf/deepseek-harness-desktop, empacota o harness no Tauri e fornece um instalador de aproximadamente 5 MB para Windows, macOS e Linux sem nenhuma configuração do Node. Não é um lançamento oficial da DeepSeek, então trate-o como tal: no momento da escrita, ele tem cerca de 400 estrelas e foi criado um dia após o próprio harness.

Executar o DeepSeek Harness Totalmente Local com Ollama

Ollama possui uma integração first-party. A versão curta é um comando:

bashCopy
1ollama launch dsh
2

Isso instala e executa o harness com o Ollama conectado, mantendo suas configurações em ~/.ollama/launch/dsh/settings.yaml (Ollama Docs, agosto de 2026). Uma ressalva que vale a pena ler antes de assumir que tudo está offline: a pesquisa web embutida é ativada automaticamente e precisa de acesso à nuvem do Ollama mais um modelo que suporte ferramentas. Um modelo genuinamente local oferece custo zero de token, ao preço de velocidade e, geralmente, chamadas de ferramenta mais fracas.

DeepSeek Harness conectado a um servidor Ollama local executando a mesma tarefa de teste com falha

Mesma tarefa, sem viagem de ida e volta na rede, sem conta por token.

O DeepSeek Harness é Gratuito? O Que Realmente Custa Executá-lo

Resposta primeiro: o software é gratuito e licenciado sob MIT, inclusive para uso comercial. Os tokens não são gratuitos, a menos que você execute modelos localmente. Nada sobre o harness em si é medido, limitado ou vinculado a uma conta DeepSeek.

Tabela C: o que é realmente gratuito e o que não é

Um exemplo prático, usando números arredondados em vez de uma execução específica. Digamos que uma sessão de depuração como a Etapa 6 consuma 200.000 tokens de entrada e 20.000 tokens de saída, o que é realista depois que o agente leu alguns arquivos e iterou. Na taxa fixa do gateway de $0,14 in e $0,28 out, essa sessão custa cerca de 3,4 centavos. Na API first-party com taxas de cache miss fora de pico, é cerca de 5,7 centavos, e durante horários de pico, cerca de 11 centavos. Se a maior parte da sua entrada for cache hits, a first-party fica drasticamente mais barata no lado da entrada, porque a entrada com cache hit começa em $0,007 por 1M de tokens.

As alavancas práticas, em ordem de impacto: mantenha as sessões curtas para que o contexto não cresça, execute trabalhos de rotina no Flash e reserve o Pro para tarefas realmente difíceis, e use o modo Mínimo para execuções do tipo benchmark, pois ele dá ao modelo exatamente duas ferramentas e sem compactação de contexto.

Antes de Implantar: Licença do DeepSeek Harness e Riscos de Pré-visualização

Três coisas curtas, e depois o FAQ.

A licença é MIT, então o uso comercial é permitido. Mas o projeto se autodenomina uma pré-visualização para desenvolvedores e afirma, em maiúsculas, que haverá mudanças que quebram compatibilidade. Fixe uma versão e não a conecte a um pipeline de lançamento de produção ainda.

Suas credenciais ficam em texto simples em sua máquina, em $DSH_HOME/.credentials.yaml com as configurações ao lado em $DSH_HOME/settings.yaml, ambos por padrão em ~/.dsh. Se o diretório home do harness acabar dentro de um repositório, adicione-o ao .gitignore:

textCopy
1.dsh/
2

E o óbvio que é fácil esquecer: seu código vai para o endpoint que você configurou na Etapa 4. Leia os termos de dados desse provedor antes de apontar um agente para uma base de código privada.

Perguntas Frequentes

O DeepSeek Harness é gratuito?

O harness é gratuito e licenciado MIT, sem necessidade de conta ou assinatura, e você pode usá-lo comercialmente. Os tokens do modelo são faturados separadamente pelo provedor ao qual você se conectar. Apontá-lo para um modelo Ollama local oferece uma configuração genuinamente de custo zero de token, paga em hardware e velocidade.

Preciso de uma chave de API DeepSeek para instalar o DeepSeek Harness?

Não. Instalação e chave DeepSeek não estão relacionadas. npx @deepseek-ai/dsh web é executado sem nenhuma credencial. Você só precisa de uma chave quando quiser que o agente realmente chame um modelo, e pode ser uma chave para qualquer endpoint compatível com OpenAI, incluindo um servidor local.

O DeepSeek Harness pode executar modelos que não sejam DeepSeek?

Sim. Provedores personalizados aceitam openai-completions, e o adaptador cobre protocolos que podem ser descritos com uma chave, um endpoint e cabeçalhos. Adicione um segundo provedor adicionando outro bloco sob providers: em settings.yaml com seu próprio ID, URL base e modelos. Bedrock, Vertex, Azure e Codex estão deliberadamente fora do escopo porque sua autenticação precisa de mais do que isso.

Por que meu provedor personalizado retorna 401 ou "modelo desconhecido"?

Um 401 quase sempre significa que a chave está errada ou não está sendo lida da variável de ambiente nomeada em apiKeyEnv. Um modelo desconhecido geralmente significa que o endpoint não expõe um índice de modelos, então nada foi buscado: digite o ID do modelo manualmente. Verifique também a ortografia do ID do provedor, já que ele não pode ser renomeado, apenas substituído.

Onde o DeepSeek Harness armazena minha chave de API e configurações?

As chaves vão para $DSH_HOME/.credentials.yaml e as configurações de modelo escritas à mão vão para $DSH_HOME/settings.yaml, ambos em ~/.dsh a menos que você substitua DSH_HOME. As sessões ficam em $DSH_HOME/storages e os perfis em $DSH_HOME/profiles/<nome>. Mantenha todo o diretório fora do controle de versão.

O DeepSeek Harness está pronto para produção?

Ainda não, por sua própria conta. O projeto é distribuído como uma pré-visualização para desenvolvedores e avisa explicitamente sobre mudanças que quebram compatibilidade, o que é uma descrição justa de software com alguns dias de idade. Use-o para desenvolvimento local e assistência em CI, fixe a versão que você testou e releia os documentos do provedor após atualizações.

---

Verificado contra a pré-visualização para desenvolvedores do DeepSeek Harness em 17 de agosto de 2026. Este projeto envia mudanças que quebram compatibilidade por design; portanto, se um nome de campo em seu build parecer diferente do YAML acima, verifique a documentação oficial do provedor antes de assumir que a configuração está errada.