Como Instalar o DeepSeek Harness (dsh): one-liner com npx, build a partir do código-fonte, modo headless e plugins

To install Deep​Seek Harness (dsh), the open-source agent runtime Deep​Seek shipped on August 13, 2026, run npx @deepseek-ai/dsh web on a machine with Node.js 22.19 or newer. That one command downloads the 0.1.0-rc.6 preview, starts a local web UI at http://127.0.0.1:3080, and walks you through adding a model API key and a workspace on first launch. Two things to know before you start: dsh is not a model — it's the harness layer that connects a model to tools, files, and a terminal — and it's a developer preview, so expect breaking changes between releases. This guide covers both official install methods, headless mode, plugins, MCP, and the honest rough edges.

O que é o DeepSeek Harness — e o que ele não é

A fórmula interna da Deep​Seek, confirmada pelo pesquisador sênior Chen Deli, é Modelo + Harness = Agente. O modelo é o cérebro; o harness é tudo o que o transforma em algo que realiza trabalho: gerenciamento de contexto e memória, chamada de ferramentas, planejamento de tarefas, leitura e escrita de arquivos, execução de terminal, feedback de erros e a decisão de quando uma tarefa está concluída. O Deep​Seek Harness é essa camada, com código aberto sob a licença MIT em 13 de agosto de 2026 — no mesmo dia em que a versão DeepSeek V4 Pro 0813 foi disponibilizada na API da Deep​Seek.

Dois fatos definem a experiência de instalação. Primeiro, a arquitetura é "tudo é um plugin", construída sobre o Cordis, um contêiner de plugins em TypeScript — então o que você instala é um núcleo pequeno mais um conjunto de plugins que fornecem adaptadores de modelo, ferramentas, sessões e interface. Segundo, a versão no npm hoje é 0.1.0-rc.6, um candidato a lançamento que o próprio projeto classifica como prévia para desenvolvedores: o README avisa, em letras maiúsculas, que mudanças que quebram a compatibilidade estão chegando. A popularidade é real — 50.000 estrelas no GitHub nas primeiras 12 horas, 100.000 em cerca de 42 horas, e mais de 120.000 até 16 de agosto, segundo a imprensa de tecnologia chinesa — mas estrelas medem interesse, não estabilidade. Planeje sua instalação como você planeja uma prévia: rápida para experimentar, barata para descartar.

Antes de começar: os requisitos reais do sistema.

O único requisito obrigatório é Node.js. O projeto tem como alvo a faixa de versões do Node ^22.19.0 || >=24.0.0 — em termos simples, Node 22.19 ou superior, ou qualquer Node 24.x. Verifique a sua versão com node --version. Se você estiver em um Node mais antigo, a instalação via npx falhará ou se comportará mal, em vez de degradar graciosamente.

Tudo o mais é mais leve do que o pessoal model-first supõe:

• Uma chave de API do modelo. dsh executa um modelo real; ele precisa de uma chave para a API da Deep​Seek ou de qualquer provedor compatível com Open​AI que você configurar. Você pode adicionar uma na interface web após a primeira inicialização.

• pnpm — apenas para a compilação a partir do código-fonte. Instale uma vez com npm install -g pnpm.

• ~1 GB de espaço livre em disco para o pacote npm, o workspace e os registros de sessão, além do que um modelo local possa precisar (o próprio dsh não executa pesos).

• SO: a rota npm funciona em Windows, macOS e Linux. O SDK Python é mais limitado (Linux x64/arm64, macOS 14+ arm64 — sem Windows nativo), abordado abaixo.

Você não precisa de uma GPU. O harness apenas orquestra; o modelo é executado remotamente por meio de uma API.

Método 1 — o one-liner npx (recomendado para quase todos)

O início rápido oficial é um único comando, e é genuinamente um único comando:

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (current version 0.1.0-rc.6), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

A primeira inicialização tem exatamente duas etapas de configuração:

• Adicione uma chave de modelo. Configurações → Modelos → insira sua chave de API. Ela é armazenada em $DSH_HOME/.credentials.yaml e não é mostrada em texto simples depois. Em uma instalação padrão DSH_HOME tem como padrão ~/.dsh.

• Escolha um espaço de trabalho. Adicione o diretório do projeto no qual o dsh pode trabalhar. A entrada permanece bloqueada até que ambas as etapas sejam concluídas.

Então envie uma primeira tarefa — um bom teste de fumaça é "Resuma este repositório e identifique seus principais pacotes." Se o resumo voltar e as chamadas de ferramenta aparecerem no rastreamento da execução, sua instalação funciona.

Método 2 — compilar a partir do código-fonte

Prefere executar a partir do repositório? O caminho oficial é:

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

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

Você precisa de pnpm para isso (os contribuidores fixam o pnpm na versão 11.7.0). Escolha a build de origem quando quiser executar a versão mais recente do main em vez do candidato a release publicado, quando você planeja ler ou modificar o harness, ou quando você quer construir um preset personalizado a partir do diretório apps/cli/config/agent-presets/ do repositório. Para todos os demais, o caminho via npx é o mesmo software com menos cerimônia — a build de origem não desbloqueia recursos que o pacote npm não possui.

Os três perfis: web, headless e tui

dsh é fornecido com três perfis de execução, e qual deles você usa depende de onde o trabalho acontece:

• web (padrão) — a interface completa do navegador na porta 3080. É isso que npx @deepseek-ai/dsh web inicia, e é o perfil que a maioria das pessoas instalará primeiro.

• headless — uma tarefa, depois termina. dsh --profile headless "run the test suite and report failures" inicia uma sessão, executa a tarefa, grava os resultados e encerra. O runtime headless é explicitamente um processo de tarefa única: você não pode injetar instruções adicionais durante a execução, e correções são uma nova execução no mesmo workspace. Este é o perfil para integrar em scripts e CI.

• tui — uma interface de terminal para sessões controladas pelo teclado: dsh --profile tui.

Os três compartilham a mesma configuração (~/.dsh/profiles/<name>/) e o mesmo sistema de plugins, portanto mover uma tarefa da interface web para headless é uma troca de comando, não uma reinstalação.

Adicionando plugins

O gerenciamento de plugins é um comando CLI de primeira classe, não uma questão de edição no local:

npx @deepseek-ai/dsh plugin --profile web add <source>

A origem pode ser um nome de pacote npm, um repositório GitHub (github:user/repo), um tarball ou uma pasta local. A primeira instalação mais útil é o mercado oficial de plugins, que transforma a descoberta de plugins em uma interface:

npx @deepseek-ai/dsh plugin --profile web add dshmarket

Em seguida, reinicie o serviço web e abra Configurações → Plugin Market para navegar pelo catálogo e instalar com um clique. Duas regras que confundem as pessoas: os pacotes de plugins são montados na inicialização do perfil, então um plugin recém-adicionado precisa de uma reinicialização do dsh web; e um simples npm install não registra um plugin em um perfil — você deve usar dsh plugin. O ecossistema é jovem, mas não vazio: a lista awesome-dsh-plugin mantida pela comunidade já cataloga centenas de plugins em categorias como UI, habilidades, ferramentas, provedores e notificações.

MCP, as quatro predefinições e a reprodução de trajetória

Três recursos importam depois que você supera uma instalação básica:

MCP. dsh fala o Model Context Protocol por meio de um plugin integrado @deepseek-ai/dsh-mcp-client. Hoje isso é configurado em arquivos, não na interface: você edita ~/.dsh/profiles/web/cordis.patch.yml (ou um patch local do projeto) e declara o transporte de cada servidor — stdio para comandos locais como npx @playwright/mcp@latest, streamable-http para URLs remotas. Funciona, mas é a superfície menos polida na prévia; espere instabilidade ocasional e nenhuma GUI para ativar/desativar servidores.

Predefinições. dsh carrega uma de quatro predefinições de agente por sessão, e cada uma é um trade-off diferente:

• Standard — o conjunto completo de ferramentas: edição de arquivos, shell, recuperação de arquivos e da web, habilidades, planejamento, subagentes e fluxos de trabalho. O padrão do dia a dia.

• PTC (Chamada Programática de Ferramentas) — Standard mais um SDK Code Mode que permite ao modelo escrever programas TypeScript para orquestrar chamadas de ferramentas em múltiplas rodadas. Mais poderoso, mais efeitos colaterais.

• Mínimo — apenas bash e um editor de arquivos, nada mais. Feito para benchmark de modelos e reprodução mínima; o modo que a documentação da API DeepSeek V4 Flash referenciou quando divulgaram suas próprias pontuações de agente rodava em "Deep​Seek Harness minimal mode."

• Criação — um playground em tempo de execução: inspecione e carregue plugins Cordis na memória, experimente e consolide uma combinação funcional em um novo preset.

Replay de trajetória.Cada execução grava um log de sessão somente de acréscimo — prompts do sistema, raciocínio, chamadas de ferramentas e seus resultados, agendamento de subagentes. A visualização Trajectory permite inspecionar por origem, retomar, bifurcar, pesquisar e reproduzir uma execução. Esse é o depurador para o trabalho de agentes: quando uma tarefa falha, você não executa novamente e espera; você reproduz a trajetória com falha, bifurca no passo incorreto e testa uma correção sem descartar o original.

A opção do SDK Python

Se você preferir usar o harness a partir do Python em vez de um navegador, há um SDK oficial: pip install deepseek-harness-sdk. Ele inclui o runtime dsh (a wheel do pip traz o runtime Node, então não é preciso instalar Node separadamente), e o uso é um gerenciador de contexto: crie uma instância de Deep​SeekHarness, chame run("task"). Ele herda variáveis de ambiente padrão como DEEPSEEK_API_KEY e DEEPSEEK_BASE_URL, portanto trocar de provedor é uma mudança de configuração. O problema: é Python 3.10+ e suporta apenas Linux x64/arm64 e macOS 14+ arm64 — não há wheel nativa para Windows, o que é uma lacuna real se o Windows for seu host. No Windows, opte pela rota do npm.

Apontando o dsh para os modelos que você paga.

O dsh precisa de uma chave de API do modelo e é deliberadamente agnóstico em relação ao provedor: Configurações → Modelos aceita um provedor personalizado com uma URL base compatível com Open​AI (em settings.yaml, isso é api: openai-completions, baseURL e models, que é uma lista). O padrão é a própria API da Deep​Seek; um provedor personalizado é onde um gateway de roteamento se torna útil.

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. That gives you DeepSeek V4 Flash (deepseek/deepseek-v4-flash-0731, about $0.15 per million input tokens and $0.29 per million output) and DeepSeek V4 Pro (about $0.44/$0.88), both at provider list price with no token markup, plus automatic failover if a provider wobbles. For dsh, the practical win is that you can run the cheap V4 Flash for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

Para ser claro sobre os limites: o OrcaRouter hospeda, dos modelos, as chamadas dsh; ele não hospeda o dsh em si. O dsh é um runtime de agente local, e você o executa na sua própria máquina.

Onde este guia falha para você — problemas honestos com a prévia

Um tutorial de instalação que apenas informa o que digitar está fazendo metade do trabalho. Aqui está o que a prévia erra hoje, para que você não descubra isso às 2 da manhã:

• Quebras de compatibilidade são uma promessa, não um aviso. Você está na versão 0.1.0-rc.6. Chaves de configuração, a API de plugins e os formatos de presets podem mudar sem aviso. Trate ~/.dsh como um estado descartável — o custo de uma atualização ruim é uma reinstalação, e isso é aceitável neste estágio apenas porque a instalação é um único comando.

• Você não precisa do dsh para usar os modelos Deep​Seek como agente. Se seu único objetivo hoje é o DeepSeek V4 Flash ou o DeepSeek V4 Pro em um agente, o endpoint compatível com Anthro​pic da Deep​Seek já funciona no Claude Code e em outras ferramentas de agente sem nenhum software novo. dsh é uma opção oficial, não um pré-requisito. Pule esta instalação até que você queira especificamente o harness nativo.

• O MCP é configurado por arquivos e, ocasionalmente, instável. Sem GUI, sem opção de iniciar/parar por servidor, e relatos práticos descrevem falhas intermitentes. Reserve tempo para depurar YAML se o seu fluxo de trabalho depender de servidores MCP.

• A confiança em plugins é uma decisão de segurança. Plugins de terceiros são executados dentro do processo principal do harness, e não há verificação de assinatura ou de origem no momento da instalação. Instale apenas plugins que você leu ou que venham de uma fonte em que confie, e teste-os em um espaço de trabalho descartável antes de usá-los em trabalho real. O danger-full-access, um perfil de sandbox, pode modificar qualquer arquivo visível — restrinja-o a checkouts descartáveis.

• Existem bugs conhecidos na prévia. Um loop bash travado é um modo de falha documentado (interrompa e tente novamente), e o comportamento em sessões de longa duração ainda está sendo estabilizado.

• Compilações não oficiais para desktop são uma armadilha. Vários wrappers da comunidade empacotam o dsh como um aplicativo de desktop que se instala com um clique, com um runtime Node embutido. Eles funcionam, mas não são assinados nem mantidos pela Deep​Seek; se você usar um, estará confiando a terceiros uma ferramenta que terá as permissões do seu sistema de arquivos.

• Se você precisa de estabilidade em produção, aguarde uma versão não-rc. O harness é poderoso, mas ainda imaturo. Para uma stack de agentes em produção, um harness maduro e testado em batalha — ou a rota de endpoint compatível com a Anthro​pic — é a escolha defensável até que o dsh alcance uma tag estável.

Conclusão

Instalar o Deep​Seek Harness é genuinamente uma tarefa de um único comando em qualquer máquina com Node 22.19+: npx @deepseek-ai/dsh web, adicione uma chave de modelo e um workspace, envie uma tarefa de teste. Escolha a build a partir do código-fonte apenas se quiser modificar ou rastrear a main; use o modo headless para scripts; adicione o mercado de plugins logo no início; e trate o MCP como um trabalho em andamento. A ressalva honesta é a mesma que o projeto imprime em seu próprio README: esta é uma prévia 0.1.0-rc e ela vai quebrar coisas no caminho até a versão estável. Esse é o trade-off certo se você quiser ver para onde a Deep​Seek está levando a camada de agentes — e os modelos que ela executa, DeepSeek V4 Flash e DeepSeek V4 Pro, estão disponíveis hoje ao preço de tabela através do OrcaRouter, prontos para alimentar o harness do outro lado da instalação.