DeepSeek Harness (dsh): Instalação, Execuções headless, Avaliação de desempenho com 3 modelos

Publicado em
18 agosto 2026
Atualizado em
16 setembro 2026
Por
Jacob Lloyd — escrito com ajuda de IA, depois do projeto
Tempo de leitura
18 min de leitura

Em termos simples: A DeepSeek lançou um “agente de programação” gratuito e de código aberto: um programa que lê seu projeto, edita arquivos e executa comandos para você, assim como o Claude Code. Este artigo mostra como o instalei no meu PC com Linux, configurei para iniciar automaticamente, direcionei tanto aos modelos em nuvem da DeepSeek quanto a um modelo rodando no meu próprio hardware, e o testei em 5 pequenas tarefas de programação reais. Todas as 15 execuções foram bem-sucedidas; as execuções na nuvem custaram apenas alguns centavos. Porém, ainda existem alguns pontos que precisam ser aperfeiçoados.

Seis segundos: arquivo criado, programa executado, resposta impressa e código de saída 0. Foi isso que o DeepSeek Harness (dsh) fez com a primeira tarefa que lhe passei. O DeepSeek lançou-o em 13 de agosto de 2026 como um agente de programação licenciado sob a MIT, baseado numa única premissa: tudo é um plugin, incluindo o adaptador do modelo, as ferramentas, o ambiente de execução e o próprio ciclo de operação do agente. Instalei-o na mesma semana, apontei-o para os modelos em nuvem do DeepSeek e para um modelo rodando na minha própria placa de vídeo, e executei nele um pequeno conjunto de tarefas. A seguir, detalho o que foi necessário, quanto custou e onde houve dificuldades.

Resumo rápido

  • O que é: um agente do tipo Claude Code (lê e edita arquivos, executa comandos shell, mantém um plano de ação e gera subagentes) distribuído como um pacote npm. Possui uma interface web em 127.0.0.1:3080 e um modo headless que imprime apenas uma resposta e encerra a execução – este último foi criado especialmente para scripts.
  • Quanto custa: o software é gratuito. O meu conjunto de testes com 5 tarefas custou cerca de 3 centavos no V4-Flash e cerca de 7 centavos no V4-Pro, considerando as tarifas máximas; no modelo local, não houve custo algum.
  • O resultado: 15/15 tarefas foram concluídas com sucesso tanto no V4-Flash quanto no V4-Pro e num modelo Gemma-4-26B rodando localmente, na versão 0.1.0-rc.7; o tempo total de execução ficou entre 43 e 56 segundos. Num cenário real (compilar e verificar links de um site com 290 páginas), ele até percebeu, sem que eu pedisse, que o meu manual de procedimentos estava desatualizado.
  • O que é necessário: Node.js, além de uma chave API do DeepSeek ou qualquer servidor compatível com a OpenAI. Eu utilizei ambos os métodos.
  • A ressalva: trata-se de uma versão prévia para desenvolvedores. O README adverte que funcionalidades podem deixar de funcionar entre versões; portanto, é preciso fixar a versão e re-testar após atualizações.

Atualização em 16/09/2026: os testes aqui descritos foram feitos em agosto, na versão 0.1.0-rc.7. Desde então, passei para a versão 0.1.5-rc.1; o seu README também menciona perfis SDK e ACP. Além disso, retirei do meu ambiente, em 09/09/2026, o Reasonix – o outro agente de programação que este artigo usava para comparação; essa comparação agora permanece apenas como uma breve nota histórica no final do texto.

O caminho, do básico ao avançado

Os passos 1 a 3 permitem que você tenha um agente funcional em cerca de dez minutos. Os passos 4 e 5 transformam esse agente em algo que outros softwares possam chamar.

O que você obtém no final

A parte que eu realmente uso é o modo headless. A partir de uma pasta de projeto:

$ cd ~/scratch/dsh-demo
$ dsh --profile headless "Create fizz.py that prints FizzBuzz for 1..15 and run it; reply with the program output only."

1
2
Fizz
4
Buzz
…
FizzBuzz
$ echo $? 0

As aspas triplas são próprias do dsh: ele envolve sua resposta em uma caixa de código Markdown. Ele não escreve nada fora da pasta onde foi iniciado (o modo de permissão padrão é workspace-write). Ele exibe apenas a mensagem final no stdout e salva cada execução para que você possa abri-la posteriormente na interface web, visualizando cada chamada de ferramenta e a contagem de tokens.

A melhor prova disso foi um trabalho real, não algo fictício. Apontei o dsh para a pasta de código-fonte deste site e pedi que lesse o manual do projeto, executasse os comandos de compilação e verificação de links, e gerasse um relatório, sem qualquer edição ou publicação. Em 53 segundos, ele leu o manual, executou os comandos corretos e apresentou os resultados: 290 páginas, 1.752 imagens, nenhum link quebrado, além do tempo de compilação. Depois, sem que eu pedisse, ele notou que o manual ainda mencionava “288 páginas” e sinalizou essa discrepância. Esse é o tipo de tarefa simples que agora passo para o dsh sem pensar duas vezes.

A interface web segue o layout padrão de 2026: sessões à esquerda, chat no meio e uma página de configurações para os modelos. Um bom hábito: cole a chave API naquela página de configurações, não em um arquivo de configuração.

A interface web do dsh integrada a um app de chat: uma sessão concluída 'Create and run hello.py' exibe as etapas de injeção de contexto, Think, Write e Bash, a resposta 'hello from dsh', além de estatísticas como número de turnos, etapas, latência e taxa de acerto do cache; abaixo, uma barra de status com o status 'Running', um menu suspenso definido para DeepSeek-V4-Flash e botões Start, Restart e Stop
A interface web do dsh (capturada em agosto, integrada ao meu próprio app de chat). Uma sessão concluída mostra as etapas executadas (Think → Write → Bash) e as estatísticas por turno. A barra inferior é o controle do meu app para a unidade systemd e o modelo padrão; não faz parte do dsh.

Passo 1: instalação (dois minutos)

É apenas um pacote npm. Eu mantenho um prefixo Node privado para ferramentas de agentes, de modo que nada é instalado na árvore do sistema; no meu desktop Fedora imutável, esse é o único local adequado para isso. A instalação global padrão utiliza o mesmo comando:

npm install -g @deepseek-ai/dsh
dsh --version          # 0.1.0-rc.7 when I benchmarked it
dsh web                # starts the UI, prints http://127.0.0.1:3080

Abra a URL, vá até Configurações → Modelos, cole sua chave do DeepSeek e salve. Isso cria o arquivo ~/.dsh/.credentials.yaml (com permissões 0600), e o modelo começa a funcionar imediatamente, sem necessidade de reinicialização. Se quiser automatizar esse processo, o arquivo é um simples mapeamento YAML (DEEPSEEK_API_KEY: sk-…). Eu criei o meu a partir do arquivo de variáveis de ambiente que meus outros serviços já utilizam; assim, a chave nunca aparece no histórico do shell nem em arquivos de configuração.

Duas coisas importantes para saber antes de prosseguir:

  • O telemetria vem desativada por padrão. Quando a variável DSH_TELEMETRY_MODE não está definida, o recurso fica desligado. Verifiquei a configuração fornecida, e não os textos promocionais: o exportador OTLP existe, mas não está ativado.
  • O ambiente de sandbox é real, porém restrito. No modo padrão, as operações de gravação são limitadas à pasta onde o programa foi iniciado. As leituras, por outro lado, não têm restrições; isso está claramente descrito na documentação. Não execute o programa a partir da sua pasta pessoal para tarefas reais, e não aponte-o para pastas que contenham informações confidenciais.

Passo 2: execute-o como um serviço

A interface web é um processo Node que roda continuamente. Eu queria que ele fosse iniciado ao fazer login, sem necessidade de terminal e limitado apenas ao loopback. Uma unidade systemd do tipo --user faz exatamente isso:

# ~/.config/systemd/user/dsh-web.service
[Unit]
Description=DeepSeek Harness web UI (dsh web) on 127.0.0.1:3080
After=network.target

[Service]
WorkingDirectory=%h
Environment=DSH_HOME=%h/.dsh
# Use the path from `which dsh`. systemd does not allow comments at the end of a line.
ExecStart=/usr/local/bin/dsh web --host 127.0.0.1 --port 3080
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now dsh-web.service
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/   # 200

O parâmetro WorkingDirectory define a pasta raiz do espaço de trabalho da interface, mas ela ainda exige que o usuário escolha um espaço de trabalho antes de poder digitar qualquer coisa. Isso é um bom padrão. O CLI também não permite o uso de --host 0.0.0.0; os desenvolvedores afirmam que a vinculação a todas as interfaces “ainda não é suportada intencionalmente”. A interface web não possui sistema de login algum, então concordo com essa decisão. Caso precise acessá-la de outra máquina, configure um proxy reverso com autenticação ou use o navegador da própria máquina via área de trabalho remota – que é o que eu faço.

Passo 3: modelos num único arquivo YAML, com recarregamento automático

~/.dsh/settings.yaml contém o modelo padrão e quaisquer provedores adicionais. O dsh lê esse arquivo novamente antes da próxima solicitação, portanto não é necessário reiniciar nem fazer novo login. O meu arquivo fica assim:

agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash          # or deepseek-v4-pro

llm-deepseek:
  reasoningEffort: high             # off | low | high | max

# A local OpenAI-compatible server (mine is llama.cpp-based on a GPU rig).
llm-pi-ai:
  providers:
    local-rig:
      displayName: Local GPU rig
      apiKeyEnv: LOCAL_RIG_PLACEHOLDER_KEY    # a reference, not a value
      api: openai-completions
      baseURL: http://my-gpu-rig:1234/v1      # your server's address
      defaultContextWindow: 65536
      models:
        - id: unsloth/gemma-4-26B-A4B-it-qat-GGUF/gemma-4-26B-A4B-it-qat-UD-Q4_K_XL
          name: Gemma 4 26B-A4B (rig)

Dois detalhes me custaram dez minutos cada para resolver:

  • apiKeyEnv é uma referência, nunca um valor literal. O dsh resolve esse valor a partir do arquivo .credentials.yaml ou do ambiente. Até mesmo um servidor local sem chave de autenticação precisa de alguma credencial, pois o cliente compatível com a OpenAI exige um token de autenticação. Basta colocar qualquer valor fictício sob esse nome no arquivo .credentials.yaml.
  • O ID do provedor (local-rig acima) é permanente assim que as sessões começam a usá-lo. Para renomeá-lo, é preciso adicionar um novo provedor.

Como o arquivo YAML é toda a interface de configuração, “mudar o dsh para usar o modelo local” significa apenas editar duas linhas – algo que qualquer script ou agente pode fazer. Eu uso esse recurso para enviar tarefas simples a um modelo local gratuito e problemas complexos ao V4-Pro, sem precisar alterar mais nada.

Passo 4: chame-o a partir do seu próprio software

O pacote oficial não possui interface de usuário no terminal (TUI). Havia plugins TUI de terceiros no npm, mas em agosto eles tinham apenas quatro dias de existência e possuíam dependências workspace:* quebradas. Eu não executaria um pacote não revisado com acesso ao shell num servidor familiar. Por isso, ao integrar o dsh ao meu próprio aplicativo de chat, utilizei o que o pacote oficial oferece:

  • Execute tarefas sem interface, com uma lista fixa de argumentos. Meu servidor inicia dsh --profile headless "…", passando a tarefa como um único elemento no array argv e sem usar o shell; assim, uma tarefa contendo ; rm -rf / é apenas texto. O dsh executa uma tarefa por vez e mantém um histórico curto das respostas finais.
  • Troque de modelo reescrevendo o valor de agent-default-model no arquivo settings.yaml. Não é necessário reiniciar nada.
  • Integre a interface web num iframe, se desejar; ela não envia cabeçalhos que bloqueiam o carregamento do frame.

A única regra que vale a pena seguir: coloque tudo isso atrás do login administrativo do seu aplicativo. Uma tarefa executada sem interface equivale à execução de código arbitrário; portanto, trate a opção “executar uma tarefa” da mesma forma que trataria o uso do shell.

O benchmark: 5 tarefas, 3 modelos, 15/15

Este não é um teste científico: são cinco pequenas tarefas que eu realmente passaria para um agente de programação. Cada uma delas é executada em uma pasta nova e verificada por um script: o arquivo existe e pode ser executado? Os testes passam sem que o arquivo de teste seja tocado? A renomeação do arquivo não deixou nenhuma referência ao nome antigo? O tempo total inclui todo o processo, incluindo um prompt de sistema com cerca de 7.500 tokens. As contagens de tokens são extraídas do próprio log de sessão do dsh.

TarefaV4-FlashV4-ProGemma-4-26B (local, rig)
Responder “PONG” (inicialização + uma chamada)✅ 2,1 s✅ 2,8 s✅ 13,2 s*
Escrever e executar o FizzBuzz✅ 5,3 s · 2 ferramentas✅ 8,4 s · 2 ferramentas✅ 4,9 s · 2 ferramentas
Corrigir 2 bugs para que os testes unitários passem (sem tocar nos testes)✅ 11,7 s · 8 ferramentas✅ 15,8 s · 7 ferramentas✅ 10,4 s · 8 ferramentas
Resumir um código com 6 módulos (menos de 150 palavras)✅ 8,9 s · 9 ferramentas✅ 10,9 s · 7 ferramentas✅ 12,1 s · 7 ferramentas
Renomear uma função em 3 arquivos + testes; verificar se tudo funciona✅ 15,1 s · 14 ferramentas✅ 18,2 s · 12 ferramentas✅ 12,2 s · 11 ferramentas
Tempo total43 s56 s53 s
Tokens (miss de entrada / leitura do cache / saída)42,6k / 136k / 4,5k41,4k / 107k / 3,2k40,5k / 237k / 5,6k
Custo nas taxas de pico (fora do pico é metade)≈ $0,027≈ $0,072$0 (apenas custo de energia elétrica)

*Primeira chamada após o modelo ser carregado no rig; as demais tarefas mostram velocidades mais altas. Versão 0.1.0-rc.7, 18/08/2026. Os preços foram extraídos da página de preços do DeepSeek naquele dia: Flash custa $0,014 / $0,44 / $1,32 por milhão de tokens (cache hit / miss / saída); Pro custa $0,044 / $1,32 / $3,96. O script de benchmark foi descartado depois, então não posso confirmar se a verificação do resumo contou as palavras corretamente.

O que a tabela revela:

  • O cache de prompts influencia diretamente o custo. Cada tarefa utiliza cerca de 7,5k tokens do prompt de sistema; porém, após o primeiro passo, quase tudo é lido do cache, a um custo de apenas 3% do valor da falha de cache. Tarefas com múltiplos passos permanecem baratas porque o script mantém esse prefixo estável.
  • O modelo V4-Pro usou menos chamadas a ferramentas para obter o mesmo resultado (12 contra 14 na tarefa de renomeação). Neste conjunto de testes, o Flash foi mais rápido e custou cerca de um terço do Pro; por isso continuou sendo minha opção padrão.
  • O modelo local se saiu bem. O Gemma-4-26B (modelo misto de especialistas com 4B de parâmetros ativos, quantizado em Q4 e executado via llama.cpp em duas RTX 5090) passou em todas as tarefas. Ele leu mais contexto do cache (237k tokens contra 136k do Flash), mas seu tempo total foi competitivo. Foi a primeira vez que um modelo local se mostrou uma opção viável para essas tarefas, e não apenas uma curiosidade técnica. Claro, cinco pequenas tarefas não dizem nada sobre refatorações envolvendo 40 arquivos.

Regra de decisão que adotei: Uso o Flash para tarefas rotineiras e qualquer coisa automatizada; o Pro quando a tarefa exige menos passos ou melhor qualidade; e o modelo local quando o trabalho pode ser refeito sem custo extra e não precisa sair do ambiente local.

O teste divertido: crie um brinquedo para mim

Também queria ver o que ele faria com um pedido criativo aberto: “crie uma versão interativa em pixel art do logotipo deste site. Use apenas JavaScript puro; deve ser incorporável em qualquer lugar; ao passar o mouse algo físico deve acontecer; ao clicar, algo legal deve ocorrer. Sem dependências; teste você mesmo.” Eis o que ele criou – e está funcionando ao vivo (mais tarde, competiu contra duas criações do Kimi no desafio de widgets em pixel art):

Passe o mouse sobre ele e depois clique. Os pixels se afastam do cursor e voltam ao lugar. Um clique faz com que os pixels se espalhem em todas as direções, para depois retornarem à forma original. Funciona também no modo touch; além disso, respeita a configuração prefers-reduced-motion.
Quatro quadros do widget em pixel art: estado inicial, pixels se afastando ao redor do cursor com um brilho azul, uma nuvem cian de pixels saltando após um clique, e os pixels voltando à forma original
Estado inicial → efeito ao passar o mouse → fragmentação dos pixels → reagrupamento; tudo capturado no Chromium sem interface gráfica. Taxa de quadros: 61 fps; zero erros no console; os pixels realmente voltam à forma original.

Como foi o processo:

  • Tentativa 1 (V4-Flash): loop de 10 minutos e nenhum arquivo gerado. O pedido permitia um bitmap desenhado à mão ou gerado proceduralmente. Ele optou por desenhar à mão um bitmap 40×40 dentro de seu processo de raciocínio, mas entrou em um loop infinito: o log da sessão continha centenas de linhas com ################ e ...., até que o tempo limite foi atingido. Isso custou cerca de 2 centavos. Lição: nunca deixe um modelo desenhar pixels mentalmente.
  • Tentativa 2 (V4-Flash, pedido alterado para “gerar rasterização a partir da geometria, sem bitmaps”): 25 minutos; tudo foi entregue. Foram necessários 100 passos do modelo, 201 chamadas de ferramentas, 172 mil tokens de saída (123 mil deles relacionados ao raciocínio) e 16,3 milhões de tokens lidos do cache – cerca de 49 centavos nas taxas máximas. Ele escreveu um arquivo ll-pixel-logo.js com 399 linhas, contendo uma API global e opções definidas via atributos data-; também criou uma página de demonstração, um README, um teste unitário em Node para o rasterizador e, sem que fosse solicitado, um script Playwright que tirava screenshots do demo em três tamanhos diferentes. Ele atingiu o limite de 25 minutos enquanto aperfeiçoava o README; por isso o código de saída indicou “timeout”, embora o trabalho já estivesse concluído. Os códigos de saída podem ser enganosos em ambos os sentidos.
  • O design: o anel e os dois “Ls” inclinados lembram o logotipo original, mas são mais robustos e parecem mais “Z” do que o desenho real. Eu gastaria uns dez minutos ajustando as constantes de deformação antes de usá-lo de verdade; não o fiz – o que você vê aqui está exatamente como foi gerado.
  • Incorporar o widget aqui exigiu apenas uma linha de código, pois a política de segurança do site permite apenas scripts locais (script-src 'self') e o widget não faz nenhuma requisição de rede. O pedido pedia exatamente isso, e ele cumpriu.
  • Um custo adicional: o dsh gerou os arquivos com permissão 0600. Quando os copiei para o servidor web, o script retornou erro 403 até que executei chmod 644. Sempre corrija as permissões dos arquivos copiados de um workspace do dsh.

Armadilhas comuns

  • Trata-se de uma versão prévia para desenvolvedores; o README também diz isso. Instalei a versão 0.1.0-rc.7, três dias após o lançamento da rc.6. Os perfis, as chaves de configuração e o layout dos plugins podem mudar. Fixe a versão em qualquer automação que você utilize e execute novamente um teste básico após cada atualização.
  • No modo headless, nada é exibido no stdout até que a tarefa termine. Nada é enviado para o stdout, então uma tarefa demorada pode parecer travada. Leia o log da sessão (~/.dsh/sessions/…/session.jsonl.zstd, um arquivo JSONL compactado com zstd) ou acompanhe-o na interface web. O código de saída 0 significa “a iteração foi concluída”, não “a tarefa teve sucesso”; portanto, verifique o resultado do trabalho.
  • No modo headless, não existe a opção --model. O modelo padrão é definido no arquivo settings.yaml; altere-o lá (a configuração é recarregada dinamicamente) ou na interface web.
  • Os servidores locais sem autenticação requerem uma credencial fictícia; além disso, os IDs dos provedores são permanentes. Consulte o Passo 3.
  • A interface web utiliza caminhos absolutos (/assets/…, /api), portanto não é possível hospedá-la sob um subcaminho atrás de seu próprio proxy reverso sem reescrever os caminhos. É melhor incorporá-la ou fornecer um hostname próprio para ela.
  • O idioma da interface segue o do seu navegador. O arquivo index.html inclui lang="zh-CN"; ao abrir a página, aparece primeiro uma caixa de diálogo “Aviso de Testes Internos”. Clique em “Continuar”; depois disso, para mim, tudo ficou em inglês.
  • O processo de instalação executa scripts postinstall (node-pty, koffi, protobufjs); o npm alerta sobre isso. Não detectei nada malicioso, mas são códigos nativos sendo compilados no seu diretório de instalação. Esse é mais um motivo para usar um prefixo privado em vez do padrão do sistema.
  • Versão do Node: a rc.7 exige o Node 22.19+ ou 24; versões LTS mais antigas não conseguem executá-la. Verifique o README da versão que você instalar.

Nota histórica: dsh ao lado do Reasonix

Em agosto, usei o dsh junto com o Reasonix, um agente de terminal desenvolvido por terceiros. A divisão de funções era simples: o Reasonix era uma interface TUI que eu abria quando queria interagir diretamente com o agente; já o dsh era o que os meus outros softwares chamavam. Retirei o Reasonix da minha configuração em 09/09/2026, e agora o dsh é o meu principal agente de programação. Se você estiver decidindo entre eles, a principal diferença é que o dsh possui um modo headless no qual um único comando gera uma única resposta e um único código de saída – o que facilita a automação por scripts. Já a interface TUI pressupõe a presença de um humano digitando no teclado.

O que isso significa para mim

O modo headless é a abordagem ideal para um agente de programação que outros softwares possam invocar: um comando, uma resposta, um código de saída e um log que pode ser auditado. A seleção do modelo por meio de arquivos YAML permite que o script chamador decida qual modelo é mais adequado para a tarefa. Se você já possui um servidor de modelos local, experimente as mesmas cinco tarefas. Dez centavos em créditos da API e uma pasta temporária são todo o comprometimento necessário.

Relacionado: DeepSeek Everywhere (integração do DeepSeek ao Claude Code e a um stack de agentes), Kimi K3 como agente de programação (as mesmas cinco tarefas, executadas novamente com o dsh em setembro), bench-llm e seu sucessor CrucibleForge (ferramentas para testar modelos locais de forma mais aprofundada do que fiz aqui), e Reasonix (o agente terminal que usei antes do dsh; agora descontinuado).


← Mais de IA e LLM Local