Instalando o DeepSeek Harness (dsh)

O DeepSeek Harness — dsh na linha de comando — é o harness de agente que a DeepSeek AI lançou em 13 de agosto de 2026 sob licença MIT. Este guia cobre como colocá-lo para rodar, como entender o único arquivo de configuração que decide o que a sua instalação realmente consegue fazer, e como puxar um plugin dos 36712 repositórios que indexamos.

Leia isto primeiro

O dsh é uma prévia para desenvolvedores. O README avisa, em maiúsculas, que haverá mudanças que quebram a compatibilidade. Tudo abaixo descreve a prévia como ela está em 14 de agosto de 2026 — confira o repositório antes de colar um comando num script com o qual você se importa.

Pré-requisitos

Você precisa do Node.js. O repositório declara uma faixa de engines de ^22.19 || >=24, então um runtime mais antigo ou se recusa a instalar ou falha depois de um jeito que parece bug do harness. Confira o que você tem antes de começar:

node -v

Pelo caminho do npx, essa é a lista inteira de requisitos. Se quiser compilar a partir do código, você também precisa de git e pnpm, o gerenciador de pacotes para o qual o repositório está configurado. Nada nesta página pede que você instale o dsh no sistema todo, e enquanto a prévia estiver mudando tão rápido, uma versão fixada por projeto é mais fácil de raciocinar do que um binário global que você instalou e esqueceu.

Início rápido com npx

Um comando já entrega um harness rodando com a interface web:

npx @deepseek-ai/dsh web

O npm baixa o pacote e o harness serve a interface web em http://127.0.0.1:3080. Esse endereço é de loopback: ele responde na sua máquina e em nenhum outro lugar, o que é o padrão certo para uma ferramenta capaz de ler seus arquivos e executar comandos.

A CLI também aceita a flag --profile — dsh --profile <profile> — que escolhe o conjunto de plugins carregado na inicialização. Entre os perfis que vêm de fábrica está o headless. Rode dsh --help na sua própria versão em vez de confiar numa lista escrita um dia depois do lançamento: perfis e conjuntos disponíveis são exatamente o tipo de coisa que uma prévia reorganiza entre versões.

Rodando a partir do código-fonte

Compilar a partir do repositório vale os minutos extras se você pretende escrever um plugin, porque assim você lê as APIs reais dos pacotes em vez de deduzi-las de um README:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Rode a compilação antes do primeiro pnpm dsh web — a sequência documentada espera isso. Você chega à mesma interface web na porta 3080, mas agora contra a árvore de trabalho, então dá para corrigir um pacote, recompilar e ver o resultado. Esse também é o jeito mais rápido de descobrir o que realmente mudou numa versão, já que uma prévia que se move assim tão rápido tende a ultrapassar a própria documentação.

Onde o cordis.yml entra

A ideia organizadora do dsh é que tudo é um plugin. Modelos, ferramentas, skills, sessões, sandboxes, sistemas de arquivos, o laço do agente, a orquestração e a interface de usuário são todos plugins carregados num runtime compartilhado. Esse runtime é o Cordis, o metaframework sobre o qual o harness é construído; @deepseek-ai/cordis é uma peer dependency de todo pacote do harness.

Quais plugins carregam, e com quais opções, é decidido por uma configuração de loader cordis.yml:

# cordis.yml
plugins:
  dsh-example-plugin:

Cada chave sob plugins: nomeia um plugin; o bloco abaixo dela é a configuração daquele plugin, ou nada, se os padrões servirem. Os pacotes oficiais são publicados como @deepseek-ai/dsh-<name>, e a chave do loader costuma ser o nome do pacote sem o escopo npm. Autores de plugins às vezes escolhem outra chave, então o README do plugin que você está adicionando vale mais do que qualquer regra de bolso — inclusive esta.

Adicionando um plugin da comunidade

Adicionar um plugin são dois passos: instalar o pacote e depois registrá-lo na sua configuração de loader.

npm install dsh-example-plugin
# cordis.yml
plugins:
  dsh-example-plugin:

Reinicie o harness e o plugin carrega junto com todo o resto. Para achar algo que valha a pena instalar, navegue pelos 15491 plugins verificados ou filtre por categoria. Verificado quer dizer que encontramos uma dependência do runtime Cordis ou um cordis.yml no repositório, então eles vão realmente carregar. Ao todo indexamos 36712 repositórios; o resto carrega um topic dsh-plugin no GitHub sem essa ligação, o que importa porque esse topic também é o mecanismo de descoberta: se você publicar um plugin, colocar o topic é como o ecossistema encontra você.

Solução de problemas

A instalação falha com erro de engine ou de sintaxe

Quase sempre é Node.js antigo. O repositório exige ^22.19 || >=24; abaixo disso a instalação pode falhar ou lançar um erro de parsing no fundo de alguma dependência, o que parece pacote quebrado mas não é. Confira node -v e atualize — um gerenciador de versões como nvm ou fnm é o caminho menos invasivo se outros projetos da máquina precisam de runtimes mais antigos.

A porta 3080 já está em uso

Alguma outra coisa está segurando a porta — com frequência uma execução anterior do dsh que nunca terminou. No macOS ou Linux, encontre-a com:

lsof -i :3080

Pare esse processo e inicie de novo. Se preferir mover o harness em vez do outro serviço, consulte dsh --help e as opções do plugin web no seu cordis.yml em vez de adivinhar o nome de uma flag: a superfície de opções da prévia ainda está mudando, e uma flag que funcionou num post de blog semana passada pode não existir na sua build.

Funcionava semana passada e agora não funciona

Esse é o modo de falha esperado de uma prévia para desenvolvedores, não um mistério. O README diz sem rodeios que mudanças que quebram compatibilidade estão vindo, e um plugin construído sobre um formato de loader mais antigo pode parar de carregar silenciosamente depois de uma atualização do harness. Dois hábitos ajudam: fixar a versão que você testou e verificar quando o plugin recebeu o último push antes de culpar a sua própria configuração — nossas fichas mostram essa data em toda página de plugin.

npx @deepseek-ai/dsh@<version> web

Quando algo está genuinamente quebrado e não apenas renomeado, o projeto mantém o GitHub Discussions e um Discord, e ambos estão mais atualizados do que qualquer guia de terceiros consegue estar numa semana como esta.

Não sabe em qual versão fixar? Nosso changelog resume o que cada versão mudou — e quais quebram coisas.

Perguntas frequentes

Preciso instalar o dsh globalmente?
Não. O início rápido com npx baixa e executa o pacote sob demanda, e o caminho a partir do código roda a CLI via pnpm dentro do repositório clonado. Como a prévia publica mudanças que quebram compatibilidade, uma versão fixada por projeto envelhece melhor do que um binário global que você instalou e esqueceu.
O DeepSeek Harness é gratuito?
O harness em si é código aberto sob licença MIT, então você pode executar, modificar e redistribuir sem custo. O modelo para o qual você o aponta é outra história, e o que aquele provedor cobra não é coberto pela licença do harness.
Por que a interface web escuta em 127.0.0.1 e não no meu endereço de rede?
Esse endereço é de loopback, ou seja, a interface só responde na máquina que a iniciou. Nada na sua rede local alcança http://127.0.0.1:3080 a menos que você coloque deliberadamente um proxy ou túnel na frente — um padrão sensato para uma ferramenta que pode executar comandos na sua máquina.
Dá para usar o dsh em produção hoje?
Não com segurança. O DeepSeek Harness é uma prévia para desenvolvedores lançada em 13 de agosto de 2026, e o README avisa em maiúsculas que haverá mudanças que quebram compatibilidade. Trate-o como algo para experimentar e para escrever plugins, não como infraestrutura que você colocaria num plantão.
O que exatamente é o cordis.yml?
É a configuração de loader que decide com quais plugins o seu harness inicia e como cada um é configurado. Como o dsh trata modelos, ferramentas, skills, sessões, sandboxes e até a interface como plugins, o cordis.yml é na prática a definição do que a sua instalação consegue fazer.

Para onde ir agora

Se o modelo de plugins é novidade para você, comece por o que é de fato um harness de agente — isso explica por que o dsh coloca tanta coisa atrás de uma configuração de loader. Se você está pesando o dsh contra uma ferramenta que já usa, nós o comparamos com o Claude Code, incluindo as partes em que o dsh claramente ainda não está pronto.