Como manter o DeepSeek Harness privado em um VPS

O que é o DeepSeek Harness

O DeepSeek Harness (dsh) é um runtime de agentes Node.js que pode ser executado num VPS (servidor privado virtual). A forma segura de o executar é vinculá-lo a 127.0.0.1 e aceder-lhe no browser através de um túnel SSH (secure shell). O Harness disponibiliza uma interface web (user interface) na porta 3080, em vez de funcionar num terminal. Esse servidor web não exige uma palavra-passe própria. Por isso, publicar a porta 3080 dá a qualquer pessoa que a encontre acesso a um agente que lê os seus ficheiros e executa comandos com a conta do seu utilizador Linux.

A DeepSeek lançou-o em 13 August 2026 sob a licença MIT, como o pacote npm @deepseek-ai/dsh. O projeto descreve-se como uma versão de avaliação para programadores e indica que são esperadas alterações incompatíveis. Todos os números de versão abaixo correspondem a um instantâneo de August 2026. Consulte o repositório antes de copiar qualquer parte deste conteúdo para um sistema importante.

Uma ideia orienta todo o design: tudo é um plugin. O adaptador do modelo, o registo de ferramentas, o log da sessão, o sandbox, o agendador e o próprio loop do agente são plugins carregados num contexto partilhado, e qualquer um deles pode ser substituído. Não existe um núcleo privilegiado que os plugins apenas complementem. É isso que torna o harness interessante para testar, mas também é aí que reside o único risco real. A vantagem dessa troca depende do ponto de comparação, e a comparação com Claude Code e Omnigent coloca o design em que tudo é plugin ao lado de duas outras respostas sobre o acoplamento ao modelo, a licença e os recursos de um VPS que cada opção exige.

Um harness não é um modelo

O harness executa o ciclo do agente. O raciocínio ocorre num modelo noutro local, por isso nada funciona até lhe fornecer uma chave de API (interface de programação de aplicações) ou o endereço de um endpoint de modelo alojado por si. Tudo neste artigo é configuração do harness, não comportamento do modelo, e é importante distinguir os dois antes de perder uma tarde a tentar descobrir de que lado surgiu um problema.

A configuração é feita na interface, em Settings e depois em Models. O catálogo tem cartões prontos para os principais fornecedores de API (DeepSeek, OpenAI, Anthropic), onde cola uma chave. "Add a custom provider" é a opção mais interessante: recebe um ID do fornecedor, um nome de apresentação, um URL base, um protocolo de API e uma credencial, e usa o protocolo compatível com OpenAI. Assim, funciona com qualquer gateway ou servidor local que implemente esse protocolo. Os fornecedores personalizados também podem consultar o endpoint compatível com OpenAI GET /models para preencher automaticamente a lista de modelos.

É assim que aponta o harness para um modelo no mesmo VPS. O Ollama expõe uma API compatível com OpenAI em http://127.0.0.1:11434/v1/ e exige que o campo da chave de API seja preenchido com qualquer texto, por convenção ollama, porque o campo é obrigatório e depois é ignorado. A questão mais difícil é saber se um modelo suficientemente pequeno para caber no seu VPS consegue executar bem um agente, e a diferença entre Ollama e vLLM como servidores de modelos locais determina quanta RAM essa escolha consome.

As chaves introduzidas na interface são apenas de escrita. O harness armazena-as em $DSH_HOME/.credentials.yaml e mantém apenas uma referência à credencial em settings.yaml. $DSH_HOME tem como valor predefinido ~/.dsh. Trate esse ficheiro como um ficheiro de palavras-passe, porque é isso que ele é: qualquer pessoa que o leia pode gastar o seu orçamento de API. Se preferir editar diretamente esses ficheiros em vez de navegar pela interface Settings, o guia de configuração do dsh sobre ficheiros de configuração, chaves e endpoints de modelos explica a função de cada chave e o que sai do seu sistema em cada modo.

O que é necessário antes da instalação

• uma VPS com Ubuntu 24.04 ou outra distribuição Linux atual, com acesso SSH
• Node.js 22.19 ou mais recente na linha 22.x, ou Node.js 24 ou superior, que é a versão usada para compilar e testar o projeto
• uma conta de utilizador normal, não root, porque o agente executa comandos shell como o utilizador que iniciou o processo
• pnpm no PATH se planeia instalar plugins, porque o comando do plugin o executa através da shell
• a porta 3080 fechada na firewall e na firewall de rede separada do fornecedor

O pacote nodejs do Ubuntu é mais antigo do que o necessário para o harness. Por isso, instale o Node a partir do NodeSource ou do nvm, em vez de recorrer ao apt install nodejs. Se a VPS for nova, vale a pena reforçar o SSH antes de qualquer outra coisa durante dez minutos, porque o túnel de que vai depender só é tão seguro quanto o servidor SSH que está por trás dele.

Instalar o DeepSeek Harness numa VPS, fixado numa versão

node --version
npx @deepseek-ai/dsh@0.1.0-rc.6 web

npx transfere o pacote e executa o binário dsh. web é um alias de --profile web, que inicia a aplicação do browser, e o processo apresenta o endereço em que está a escutar. O valor predefinido é http://127.0.0.1:3080. Esses números definem a ligação, não são apenas um valor predefinido cosmético, e por que o dsh apresenta um endereço de loopback explica ao que o harness responde e ao que não responde antes de tentar aceder-lhe a partir do portátil.

Fixe a versão. npx @deepseek-ai/dsh web resolve o destino atual da etiqueta latest no momento em que o executa, e o projeto já lançou vários release candidates e informa que haverá alterações incompatíveis. 0.1.0-rc.6 é o destino de latest em 13 August 2026. Uma versão fixada significa que o servidor configurado hoje se comporta da mesma forma no próximo mês. Assim, uma atualização passa a ser uma decisão sua, em vez de um acidente descoberto depois. Quando um comando com a versão fixada ainda inicia a build errada ou recusa completamente a instalação, os erros habituais de instalação e versão do dsh explicam como limpar a cache do npx e verificar qual npm está incluído no seu Node.

Para utilização diária, instale-o uma vez em vez de voltar a resolver a versão em cada arranque.

npm install -g @deepseek-ai/dsh@0.1.0-rc.6
dsh --profile web --help

Vale a pena executar essa segunda linha, porque o launcher e a aplicação web têm conjuntos de flags separados. dsh --help apresenta as opções do próprio launcher. dsh --profile web --help apresenta as flags aceites pela aplicação web. É aí que se encontram --port, --host e --trusted-host, que pode ser repetida.

Agora confirme em que endereço está a escutar.

ss -tlnp | grep 3080

A coluna do endereço local deve indicar 127.0.0.1:3080. Se indicar 0.0.0.0:3080, a interface está acessível a partir da Internet. Pare o processo antes de fazer qualquer outra coisa.

Por que você nunca deve publicar a porta 3080

O servidor web não tem uma camada de autenticação. A configuração expõe um endereço de escuta e uma porta de escuta. Essa é toda a superfície exposta. O controlo de acesso para implementações que não usam loopback é uma definição separada de host confiável. Essa definição não é uma tela de login.

Agora considere o que existe por trás dessa porta. O agente edita ficheiros no workspace e executa comandos de shell. As credenciais do seu provider ficam armazenadas no disco, junto do agente. Portanto, uma porta 3080 aberta equivale a um shell remoto com uma interface de chat, executado com o utilizador que o iniciou e com a sua API key associada. Não é preciso explorar uma vulnerabilidade. Basta conhecer o número da porta. Os scanners encontram números de porta poucas horas depois de um host ficar online.

A CLI (interface de linha de comandos) confirma essa decisão. A partir de 0.1.0-rc.6, ela não suporta deliberadamente --host 0.0.0.0 e termina com um erro de utilização, em vez de arrancar. Essa recusa é uma funcionalidade. Não procure um patch para a remover.

Existem duas outras implementações razoáveis quando um túnel não é adequado. Coloque o servidor numa rede overlay privada, para que tenha um endereço para o qual apenas os seus próprios dispositivos possam encaminhar tráfego. É isso que um servidor de controlo Headscale autoalojado fornece. Outra opção é colocá-lo atrás de um reverse proxy que autentique o pedido antes de este chegar à porta 3080, por exemplo um servidor de single sign-on Authentik a executar forward auth. Um reverse proxy sem autenticação à frente não é um controlo de segurança. É apenas um URL mais longo.

Aceder à interface web através de um túnel SSH

Execute isto no seu computador portátil, não no servidor.

ssh -N -L 3080:127.0.0.1:3080 you@your-server

-L abre a porta 3080 no seu computador portátil e encaminha tudo o que se ligar a ela através da sessão SSH encriptada. A parte 127.0.0.1:3080 é resolvida no servidor, por isso a ligação chega ao harness a partir do loopback, exatamente como se estivesse a trabalhar na máquina. -N indica que não deve iniciar uma shell remota, porque pretende apenas o encaminhamento.

Depois, abra http://127.0.0.1:3080 no navegador local. Se a porta 3080 já estiver ocupada no seu computador portátil, altere o número do lado esquerdo: ssh -N -L 3180:127.0.0.1:3080 you@your-server, e depois aceda a http://127.0.0.1:3180. O número do lado esquerdo é local e o número do lado direito pertence ao servidor, por isso apenas o primeiro muda.

Guarde isto em ~/.ssh/config e deixe de o escrever.

Host dsh
  HostName 203.0.113.10
  User deploy
  IdentityFile ~/.ssh/id_ed25519
  LocalForward 3080 127.0.0.1:3080

Depois disso, ssh -N dsh inicia o túnel. Se o navegador indicar que a ligação foi recusada, normalmente significa que o túnel está ativo, mas não existe nenhum processo a escutar no outro lado, porque o SSH encaminha a porta independentemente de o harness estar em execução. Verifique o servidor com o comando ss acima.

Mantenha o harness em execução depois de terminar a sessão

Um comando npx termina com a sua shell. Um serviço de utilizador do systemd continua em execução e inicia novamente o harness depois de uma falha ou de um reboot. A unidade apresentada aqui é deliberadamente mínima. Se quiser executar o harness com uma conta própria e restrita, fixar a versão dentro da unidade e obter logs que possa realmente pesquisar, a configuração completa do systemd sem interface gráfica para dsh explica o procedimento.

loginctl enable-linger $USER
mkdir -p ~/.config/systemd/user
command -v dsh

enable-linger é importante porque os serviços de utilizador normalmente param quando termina a última sessão. Sem essa opção, o harness termina assim que fecha o túnel. Use o caminho absoluto apresentado por command -v dsh na unidade, porque o systemd não pesquisa o PATH criado pela sua shell de login.

[Unit]
Description=DeepSeek Harness web UI
After=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/projects/site
ExecStart=/usr/local/bin/dsh web
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

WorkingDirectory não é apenas uma questão estética. O processo dsh usa o diretório a partir do qual foi iniciado como localização predefinida no sistema de ficheiros. Por isso, um serviço iniciado no diretório errado fornece ao agente o workspace predefinido incorreto. Ainda pode escolher o workspace na interface.

systemctl --user daemon-reload
systemctl --user enable --now dsh
systemctl --user status dsh

Uma unidade que se recusa a iniciar quase sempre tem um caminho ExecStart incorreto ou uma versão do Node que o binário rejeita. journalctl --user -u dsh -n 50 indica qual dos dois é o problema. O mesmo padrão aplica-se a manter qualquer agente de programação em execução num VPS, e os modos de falha são idênticos.

O que um plugin pode fazer

Um plugin é um módulo que fornece serviços, eventos tipados e efeitos reversíveis a um contexto partilhado. Estes são os pontos de extensão que deve analisar com atenção:

• registar um fornecedor de modelos em ctx.llm
• adicionar ferramentas destinadas ao modelo em ctx.tools
• fornecer o backend da shell através de ctx.shell
• fornecer acesso ao sistema de ficheiros ou aplicar políticas através de ctx.fs
• registar comandos para utilizadores em ctx.commands
• executar tarefas em segundo plano através de ctx.jobs
• envolver processos iniciados com um backend ctx.sandbox
• intercetar pedidos e chamadas de ferramentas através dos eventos agent/* e tools/*
• estender o estado persistente da sessão
• controlar a interface através de ctx.agents

Leia essa lista como um atacante a leria. Um plugin pode fornecer a camada do sistema de ficheiros e a camada da shell, além de poder ficar entre o modelo e cada chamada de ferramenta que este fizer. Não existe nenhuma caixa de diálogo de permissões entre um plugin e esses pontos de integração, porque um plugin é código Node normal, carregado no mesmo processo que todo o resto. Instalar um plugin significa executar código de terceiros com as permissões do seu agente, e as permissões do seu agente são as permissões do seu utilizador Unix.

Esta é a mesma decisão de confiança que toma quando liga um servidor MCP a um agente numa VPS, sendo MCP o protocolo de contexto do modelo. É também por isso que executar um agente de programação com segurança numa VPS começa pela conta em que este é executado, e não pelo modelo, e por que razão os ataques à cadeia de fornecimento do npm atingem os servidores com tanta força: o passo de instalação é o comprometimento, e não aparece nenhum pedido de confirmação.

De onde vêm os plugins

Os plugins ficam nos perfis. Um perfil é uma composição com nome, armazenada em $DSH_HOME, que por predefinição é ~/.dsh, e cada diretório de perfil contém os plugins externos que instala. A CLI gere-os encaminhando os seus argumentos diretamente para pnpm, usando o diretório do perfil como diretório de trabalho.

dsh plugin --profile web add github:deepseek-harness/turtle-ui
dsh plugin --profile web remove turtle-ui

Como os argumentos chegam a pnpm sem alterações, add, remove, update e why comportam-se como em qualquer projeto pnpm, e um plugin pode ser um pacote npm ou uma referência do GitHub. pnpm tem de existir primeiro no PATH. No Node 22 e posteriores, corepack enable pnpm coloca-o nesse caminho.

A descoberta funciona através de um tópico do GitHub. Os autores dos plugins adicionam o tópico dsh-plugin ao respetivo repositório, e a consulta desse tópico é a forma de encontrar os plugins existentes. Um tópico é um rótulo que o autor aplica ao próprio repositório. Ninguém o revê nem o assina, e a página do tópico ordena os resultados pelo número de estrelas, que mede popularidade e não segurança.

Quatro hábitos mantêm isto sob controlo. Leia o código-fonte antes de instalar, porque a maioria dos plugins é suficientemente pequena para ser lida em dez minutos. Fixe a versão ou o commit exatos em vez de acompanhar um branch. Execute o harness com um utilizador que não seja proprietário de mais nada, num VPS que esteja disposto a reinstalar. Dê ao agente a sua própria chave de API, com o seu próprio limite de despesas, separado da chave usada pelos serviços de produção. Quando se sentar para ler um plugin e quiser saber que ficheiros concentram o risco, o passo a passo para analisar um plugin dsh percorre o manifesto, o ponto de entrada e os pontos de extensão que um plugin regista.

Se preferir comparar arquiteturas antes de escolher uma, o harness multiagente Omnigent resolve o mesmo problema com uma estrutura diferente, e as vantagens e desvantagens tornam-se evidentes quando entram em cena os plugins. Se acabar por manter dois ou três no mesmo servidor em vez de escolher um vencedor, colocar todos os harnesses atrás de uma API autoalojada evita um túnel por porta, mas acrescenta mais um serviço que tem de ficar associado à interface loopback e receber uma palavra-passe real desde o primeiro dia.

O que falha primeiro

Node é demasiado antigo. O projeto requer Node 22.19 ou uma versão mais recente da linha 22.x, ou Node 24 ou posterior, e a CI testa essas versões. Um runtime mais antigo falha no arranque porque o código usa sintaxe e APIs que essa versão não suporta. Execute node --version antes de qualquer outra coisa.

A porta 3080 já está ocupada. Pode ser outro harness, um processo antigo ou uma aplicação não relacionada que também use a porta 3080. Encontre o processo com ss -tlnp | grep 3080 e depois pare-o ou inicie o harness noutra porta com dsh web --port 3180. --port pertence à aplicação web, por isso deve ser executado depois de web.

O browser não consegue ligar-se através do túnel. Confirme que acedeu a 127.0.0.1 e não ao endereço público do servidor, porque a porta encaminhada só existe no seu laptop. Depois, confirme que o harness está à escuta no servidor, porque o SSH cria o encaminhamento independentemente de existir ou não um serviço a responder na outra extremidade.

dsh plugin falha imediatamente. O comando é um wrapper de pnpm, por isso a ausência do binário pnpm interrompe-o antes de qualquer trabalho dos plugins.

O agente não consegue ver o seu projeto. Por predefinição, o workspace corresponde ao diretório onde o processo foi iniciado. Assim, uma unit cujo WorkingDirectory seja o seu diretório home fornece ao agente o seu diretório home. Escolha o workspace na interface ou corrija a unit e recarregue-a.

FAQ

É seguro expor a interface Web do DeepSeek Harness na porta 3080?

Não. O servidor Web não tem autenticação própria, e o agente por trás dele edita ficheiros e executa comandos shell com a conta que iniciou o processo. A chave da API do seu fornecedor também fica armazenada no mesmo disco. Mantenha o listener em 127.0.0.1 e aceda a ele através de um túnel SSH. Uma rede privada sobreposta ou um reverse proxy que autentique todos os pedidos antes de estes chegarem à porta também funciona. A partir da versão 0.1.0-rc.6, a CLI recusa --host 0.0.0.0 e termina com um erro de utilização. Isto mostra a posição dos autores sobre essa configuração.

Preciso de uma chave da API da DeepSeek ou posso usar um modelo local?

Ambas as opções funcionam, porque o harness é um runtime, não um modelo. Em Settings e depois em Models, pode colar uma chave no cartão de um fornecedor do catálogo. Também pode escolher "Add a custom provider" e indicar um URL base que utilize o protocolo compatível com OpenAI. Um servidor Ollama local responde em http://127.0.0.1:11434/v1/ e aceita qualquer texto no campo da chave da API. As chaves são guardadas em $DSH_HOME/.credentials.yaml, que por predefinição é ~/.dsh/.credentials.yaml.

O que é que a instalação de um plugin do DeepSeek Harness realmente dá ao plugin?

As permissões da conta que executa o harness. Um plugin é código Node carregado no mesmo processo. Os pontos de extensão incluem o backend shell, a camada do sistema de ficheiros, o registo de ferramentas e os eventos que envolvem cada chamada de ferramenta. Nada isola um plugin desses pontos de integração, a menos que o próprio plugin forneça o sandbox. Leia o código-fonte antes de instalar e execute o harness com uma conta que não seja proprietária de nada que queira proteger.

Que versão devo instalar e ela continuará a funcionar?

Instale uma versão exata, por exemplo npx @deepseek-ai/dsh@0.1.0-rc.6 web. Era essa a versão indicada pela tag latest em 13 August 2026. O projeto identifica-se como uma versão preliminar para programadores e informa que são esperadas alterações incompatíveis. Por isso, um comando sem versão fixada pode comportar-se de forma diferente de um dia para o outro. Consulte o repositório antes de atualizar e espere alterações nas chaves de configuração e nas interfaces dos plugins enquanto a versão começar por 0.