Como rodar o DeepSeek Harness a partir do código-fonte com git clone e pnpm

Fala aí, beleza? Tem uma diferença grande entre USAR uma ferramenta e ter o código dela aberto na tua frente

Rodar pelo pacote publicado é um comando e pronto, tu tá dentro

Rodar o DeepSeek Harness a partir do código-fonte é outra pegada: tu clona o repositório, instala as dependências, builda e sobe a Web UI com os artefatos que TU gerou

O projeto é da DeepSeek AI, licença MIT, e está em developer preview na versão 0.1 (o próprio README avisa que virão mudanças que quebram compatibilidade)

A arquitetura é toda baseada em plugins Cordis: modelo, ferramentas, skills, sessão, sandbox, storage, loops, agendamento e até a própria UI são plugins

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Então este guia serve pra quem quer ler esse código, alterar os presets de agente ou acompanhar o desenvolvimento de perto

Se o teu interesse é o modelo rodando na tua máquina, isso é outro papo: aí vale ver qual hardware pra rodar local, que é uma discussão separada do harness

Bora ver na prática? 🙂

O que você precisa antes de clonar o repositório

Antes de sair digitando git clone, arruma a toolchain

O checkout não perdoa versão velha, e é melhor descobrir isso agora do que no meio do install

• Node.js na faixa declarada pelo projeto: engines: ^22.19 || >=24, ou seja, Node 22.19+ na linha 22.x, ou Node 24 pra cima
• pnpm 11.7.0, que está pinado no package.json do repositório
• Git 2.26 ou mais novo, exigido pelo setup de desenvolvimento por causa da configuração específica de worktree usada no setup de hooks

E se meu Node for mais antigo?

O engine check falha

Não é aquele caso de "vai que cola": a faixa está declarada no projeto, runtime mais antigo bate de frente com ela

Atualiza o Node pra linha 22.19+ ou pra 24 antes de qualquer coisa, é o caminho mais curto

E o pnpm, instalo como?

O repositório pina [email protected] no package.json e orienta habilitar o Corepack quando o pnpm local não resolve por ele

Na prática: roda pnpm --version e vê se ele resolve via Corepack

Se não resolver, habilita:

corepack enable

Se você conhece o npm ou o composer, o pnpm mora no mesmo lugar mental: é o gerenciador de pacotes que instala as dependências do projeto

A diferença aqui é que o repositório quer uma versão específica dele, não qualquer uma que estiver na tua máquina

Passo a passo: do git clone à Web UI em 127.0.0.1:3080

São cinco comandos, na ordem

1. Clone o repositório oficial

git clone https://github.com/deepseek-ai/deepseek-harness.git

O erro comum deste passo: Git antigo

O setup de desenvolvimento pede Git 2.26 ou mais novo por causa da configuração de worktree no setup de hooks, então confere a versão antes de brigar com o resto

2. Entre na pasta do projeto

cd deepseek-harness

Parece bobo, mas todos os comandos seguintes assumem que tu está DENTRO do checkout

3. Instale as dependências

pnpm install

O erro comum deste passo: o pnpm da máquina não resolve pelo Corepack e você acaba instalando com uma versão diferente da que o projeto pinou

Se pnpm --version não vier pelo Corepack, roda corepack enable e tenta de novo

4. Builde os artefatos

pnpm run build

O erro comum deste passo: Node fora da faixa de engines

Se o runtime não estiver em ^22.19 || >=24, o engine check falha e você não passa daqui

5. Suba a Web UI

pnpm dsh web

Aqui tem DOIS erros comuns, e os dois pegam gente experiente

O primeiro é pular o passo 4 achando que o dsh web builda sozinho: ele não builda

O pnpm run build prepara os artefatos, e o pnpm dsh web consome esses artefatos já buildados, sem novo build

O segundo é tentar abrir a UI de outra máquina

O comando sobe a interface em http://127.0.0.1:3080 por padrão, com bind apenas em localhost

Ou seja: acessa do próprio computador que subiu o processo

Quando compensa rodar do código-fonte (e quando o npx basta)

Agora a parte honesta: nem todo mundo precisa desse caminho

O checkout compensa quando você quer botar a mão no projeto

• Ler e alterar o código, que é o motivo número um de clonar qualquer coisa
• Customizar os presets de agente, que ficam em apps/cli/config/agent-presets/ dentro do repositório
• Rodar a bateria do projeto enquanto mexe: pnpm run test (testes unitários com vitest) e pnpm run lint
• Reproduzir o build de release com pnpm run build:official, que é o equivalente local e multiplataforma do build de CI e dos artefatos de release
• Entender a arquitetura de plugins Cordis na prática, vendo modelo, ferramentas, skills, sessão, sandbox, storage, loops, agendamento e a UI como peças plugáveis

Esse último ponto é o mais subestimado

Quando TUDO é plugin, ler o código é o jeito mais rápido de sacar onde uma peça encaixa

E se a tua praia é justamente pipeline de build e automação, o assunto conversa com rodar CI no Cursor Origin, que é a mesma lógica de reproduzir localmente o que a esteira faz

Do outro lado: se você só quer USAR a ferramenta, o pacote publicado resolve

npx @deepseek-ai/dsh web

E repara que o pacote publicado carrega o mesmo estágio do projeto: a versão mais recente do @deepseek-ai/dsh no npm é a 0.1.1-rc.2, ainda dentro do 0.1 em developer preview que o README avisa que vai quebrar compatibilidade

O que o build do código-fonte exige a mais de você

Não tem almoço grátis, né? 😀

O caminho do código-fonte cobra manutenção

Manter a toolchain na faixa certa. Node em ^22.19 || >=24, pnpm 11.7.0 resolvendo pelo Corepack, Git 2.26+

Qualquer um desses escorregando e você para no engine check ou no install

Rebuildar depois de cada pull. Como o pnpm dsh web consome os artefatos já buildados, atualizar o repositório sem rodar pnpm run build de novo te deixa rodando código antigo com a impressão de estar no novo

Atenção com o que o build embute. O pnpm run build embute o ambiente DSH_CLIENT_* exato de quem chama

E se nenhuma variável estiver definida, nenhum valor público de cliente é usado

Tome cuidado! Isso significa que o artefato que sai da TUA máquina carrega o SEU ambiente, e não um padrão genérico

Vale conferir o que está definido antes de buildar algo que você pretende distribuir

E tem o estágio do projeto. O DeepSeek Harness segue em developer preview, na 0.1, com aviso explícito no README sobre compatibility-breaking changes

Quem acompanha o repositório de perto sente isso mais que quem usa o pacote publicado, porque cada pull pode trazer mudança de comportamento

Vídeo: introdução a harness de agentes

Se o conceito de harness de agentes ainda é novo pra ti, dá uma olhada neste vídeo do canal antes de mergulhar no checkout

Conclusão

Recapitulando o caminho inteiro: git clone, cd deepseek-harness, pnpm install, pnpm run build e pnpm dsh web

Cinco comandos, com a toolchain certa por baixo (Node ^22.19 || >=24, pnpm 11.7.0 pelo Corepack e Git 2.26+)

O próximo passo concreto é subir a Web UI em http://127.0.0.1:3080 e abrir apps/cli/config/agent-presets/ pra mexer nos presets de agente, que é onde o checkout começa a pagar o preço que cobrou de você

E vale acompanhar o repositório de perto: publicado em 13 de agosto de 2026, ainda em developer preview e com aviso de mudança que quebra compatibilidade no README

Coisa nova mudando rápido, do jeito que a gente gosta…

até o próximo post! 🙂