Instalando o DeepSeek Harness (dsh)

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 7900 repositórios indexados ou filtre por categoria. Desses, 3942 são verificados — ou seja, encontramos uma dependência do runtime Cordis ou um cordis.yml no repositório, então eles vão realmente carregar. O resto carrega um topic dsh-plugin no GitHub sem nada por trás, 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.

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.