DeepSeek Harness: seu próprio provedor via JoinGonka Gateway

O harness é tudo o que cerca o modelo no trabalho agêntico: o ciclo «requisição → chamada de ferramenta → resultado → próximo passo», as ferramentas de arquivo e terminal, as permissões e confirmações, o log da sessão, a compactação de contexto. O DeepSeek Harness monta isso a partir de plugins: a arquitetura «everything is a plugin» é construída sobre o framework Cordis, e qualquer nó — de uma ferramenta ao adaptador de modelo — pode ser trocado sem mexer no núcleo. O código é aberto sob licença MIT.

Não precisa instalar nada: basta ter Node.js (as linhas 22 a partir da 22.19 ou 24 e mais recentes):

npx @deepseek-ai/dsh web

O comando sobe uma Web UI em http://127.0.0.1:3080 e a abre no navegador; ao rodar por SSH, o endereço apenas é impresso no terminal. A flag --no-open inicia o servidor sem navegador, e --port muda a porta. O diretório de onde o dsh foi iniciado vira o padrão de trabalho, mas a interface só inicia a sessão depois que você escolhe explicitamente um workspace.

A camada de modelos é feita de dois adaptadores. O direto fala com a API oficial do fornecedor. O multiprovedor — dsh-llm-pi-ai — é construído sobre a biblioteca pi-ai, a mesma que sustenta o agente de terminal Pi; por ele se conectam tanto os provedores embutidos do catálogo quanto qualquer endpoint próprio. Por isso os nomes dos campos na configuração — api, contextWindow, maxTokens — são os mesmos que você já conhece do Pi.

Sobre a maturidade. O README do projeto começa com um aviso: developer preview, iterações rápidas, mudanças que quebram. Um documento à parte, o SAFETY.md, deixa claro que não houve auditoria de segurança e que o agente executa comandos gerados pelo modelo. A conclusão prática é simples: rode o dsh em um contêiner, máquina virtual ou sob uma conta separada, e mantenha backups de tudo o que ele conseguir alcançar.

Etapa 1: a chave. Cadastre-se em gate.joingonka.ai/register: após confirmar o endereço, você receberá 3M tokens gratuitos na conta. No painel, abra a seção «Chaves de API» e crie uma chave com o prefixo jg-. Vale a pena criar uma chave separada para o harness: assim o tráfego dele aparece nas estatísticas em uma linha própria.

Etapa 2: a primeira tela. Depois do aviso de status de teste (botão Continue), o dsh vai pedir a chave da API oficial («Add an API key to get started»). Ela não é obrigatória: clique em Configure later.

Etapa 3: o provedor. Abra Settings → Models e escolha Add a custom provider. Campos do formulário:

Etapa 4: os modelos. No bloco Models, clique em Fetch available models: o dsh vai pedir a lista ao gateway e abrir a janela «Choose models to add». No nosso teste apareceram os três modelos da rede —MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 e zai-org/GLM-5.3-Flash— e, depois de Add selected, o harness preencheu sozinho a janela de contexto e o teto de resposta de cada um, conforme os dados do gateway. Falta só clicar em Create provider.

Etapa 5: escolher o modelo. Feche as configurações, clique em Choose workspace e adicione o diretório do projeto. Os modelos do novo provedor aparecem no seletor; o escolhido passa a ser o modelo padrão das novas sessões.

O dsh guarda a chave separada das configurações: no arquivo ~/.dsh/.credentials.yaml, com permissões somente para o dono. No settings.yaml fica apenas o nome da referência a ela — no nosso teste, JOINGONKA_API_KEY, conforme o identificador do provedor.

Qual protocolo escolher. O gateway fala os três; o que muda é o endereço base e algumas conveniências extras:

Um provedor no dsh fala um único protocolo, então um segundo protocolo exige um segundo provedor com outro Provider ID. Para o dia a dia, a primeira opção basta; no nosso teste, o ciclo agêntico com chamadas de ferramentas funcionou nos três.

O formulário Models grava em um documento YAML comum — $DSH_HOME/settings.yaml, por padrão ~/.dsh/settings.yaml. Dá para editar direto: o botão Open configuration file no topo das configurações abre o arquivo, e os adaptadores o releem na próxima requisição — não precisa reiniciar. A versão completa para a rede Gonka:

# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    joingonka:
      displayName: JoinGonka Gateway
      apiKeyEnv: JOINGONKA_API_KEY
      api: openai-completions
      baseURL: https://gate.joingonka.ai/v1
      models:
        - id: deepseek-ai/DeepSeek-V4-Flash-0731
          name: DeepSeek V4 Flash
          contextWindow: 380000
          maxTokens: 32768
        - id: zai-org/GLM-5.3-Flash
          name: GLM-5.3 Flash
          contextWindow: 390000
          maxTokens: 8192
          reasoningEfforts:
            off: low
            high: high
        - id: MiniMaxAI/MiniMax-M2.7
          name: MiniMax M2.7
          contextWindow: 200000
          maxTokens: 8192
agent-default-model:
  provider: joingonka
  model: deepseek-ai/DeepSeek-V4-Flash-0731

O que importa aqui:

• apiKeyEnv — não é a chave, mas o nome da referência a ela. O dsh procura o valor nesta ordem: variável de ambiente no momento da inicialização, depois .credentials.yaml (onde o formulário grava), depois .env no diretório de execução, depois ~/.dsh/.env. Se você configura o harness sem navegador, basta uma linha JOINGONKA_API_KEY=jg-your-key em ~/.dsh/.env com permissões 600. Uma variável exportada depois da inicialização não será vista por um processo já em execução.
• Defina contextWindow e maxTokens explicitamente. A um modelo que o dsh não conhece ele atribui 262 144 e 32 768 tokens — o que não corresponde aos limites reais. O maxTokens definido também passa a ser o limite de resposta padrão para cada requisição.
• reasoningEfforts — os níveis de raciocínio para o menu Effort. Um modelo adicionado manualmente não tem níveis, e o menu não aparece para ele. No GLM-5.3 Flash o interruptor é binário: o valor low desliga o raciocínio, qualquer outro o mantém completo. Por isso o nível off é mapeado para low, e high passa como está. No nosso teste com off não houve nenhum bloco de raciocínio, com high eles voltaram.
• agent-default-model — o modelo para novos agentes, incluindo o modo headless. O mesmo faz a seleção de modelo na interface; aqui também dá para adicionar reasoningEffort.

Os interruptores compat que a documentação do dsh recomenda para gateways rígidos (supportsDeveloperRole: false, maxTokensField: max_tokens) não serão necessários aqui: o JoinGonka Gateway aceita tanto o papel developer quanto o campo max_completion_tokens.

O instalador npx @joingonka/setup não configura este harness: toda a conexão se resume ao formulário da seção anterior ou ao trecho YAML acima.

O jeito mais rápido de validar a integração é uma execução única a partir do diretório com o código. Coloque ao lado um arquivo pequeno com um erro óbvio e peça para encontrá-lo:

cd /path/to/project
npx @deepseek-ai/dsh --profile headless "Read calc.py and tell me in one sentence whether it has a bug."

A resposta final é impressa em stdout, e o raciocínio vai para stderr com a marca dsh: reasoning:. O agente deve chamar por conta própria a ferramenta de leitura de arquivos e responder com fundamento: na nossa execução, cada um dos três modelos da rede apontou a linha errada. Ou seja, o ciclo completo «requisição → chamada de ferramenta → resultado → resposta» se monta corretamente através do gateway.

A segunda metade da verificação fica do lado do gateway. No painel, abra «Uso»: ali dá para ver as requisições por hora e por dia, a divisão por modelos e por chaves. Se apareceu uma linha com a chave do harness e um horário recente da última requisição, o tráfego está mesmo passando pelo gateway.

Se algo deu errado, o diagnóstico geralmente se lê direto na mensagem:

O preço é o mesmo para todos os modelos da rede, portanto, a escolha depende do comportamento, não do orçamento. Abaixo estão os limites e como os modelos se comportaram em nossa execução dsh na mesma tarefa: ler um arquivo e encontrar um erro nele.

A recomendação padrão é DeepSeek V4 Flash: o trabalho dos agentes atinge rapidamente o limite do volume de contexto e da extensão da edição, e aqui há margem para ambos os parâmetros. Quando a tarefa exigir reflexão sobre uma lógica complexa, mude para GLM-5.3 Flash e mantenha o nível de raciocínio em high; para edições rápidas, o mesmo provedor oferece o nível off. O MiniMax M2.7 é uma opção equilibrada para tarefas curtas, quando o processo de raciocínio visível não atrapalha. O modelo é alterado no seletor da interface ou pela linha model no bloco agent-default-model.

A composição da rede é determinada pela votação dos participantes e muda com o tempo; a lista atual com os limites é sempre obtida via GET https://gate.joingonka.ai/v1/models — o mesmo comando usado pelo botão Fetch available models.

Ferramentas de agente consomem tokens de forma diferente a um chat: para cada frase sua, o harness adiciona um prompt de sistema e descrições de todas as ferramentas, e então conduz um diálogo de várias etapas com o modelo. Em nossa execução, a tarefa "ler arquivo e encontrar erro" levou de dois a três passos e de 14 a 22 mil tokens, sendo quase tudo isso entrada: cerca de sete mil tokens são consumidos a cada passo, mesmo antes da sua pergunta. Esse é um preço normal para a autonomia — e é exatamente por isso que o preço por token é o que decide.

Através do JoinGonka Gateway, os tokens custam $0.0069 por milhão na entrada e $0.021 por milhão na saída — o preço é o mesmo para todos os modelos da rede e é carregado nesta página de uma fonte em tempo real. Ordem de magnitude dos preços para setembro de 2026:

O pagamento é feito pelo consumo real, sem assinatura e sem cotas para o número de solicitações; o saldo e o consumo diário podem ser vistos no painel.

Versão. Enquanto o projeto estiver em status de developer preview, após cada atualização verifique se o provedor está ativo e, para reprodutibilidade, fixe a versão diretamente no comando: npx @deepseek-ai/[email protected] web.

Permissões. Novas sessões operam por padrão no modo Workspace Write — gravação dentro do diretório de trabalho; a interface solicita confirmação para operações que excedam a política. O modo pode ser alterado em Settings → General.

Repetições. Em caso de erro de rede único, o dsh repete a solicitação automaticamente — até cinco vezes, segundo a documentação —, portanto, um curto pico de carga na rede geralmente passa despercebido.

Privacidade. O gateway não armazena o conteúdo dos prompts e das respostas: nas estatísticas, permanecem apenas os agregados de consumo. O agente lê os arquivos do projeto localmente, na sua máquina.

Se precisar trabalhar com imagens — capturas de tela da interface, diagramas em fotos — inicie um segundo provedor com um modelo capaz de visão: o dsh mantém vários provedores simultaneamente, e os modelos da rede Gonka são textuais.

O DeepSeek Harness não é o único agente lançado pelo laboratório desenvolvedor de modelos: a Z.ai, autora do GLM, possui o ambiente ZCode, e a MiniMax possui o MiniMax Code de terminal. Ambos se conectam ao mesmo gateway com a mesma chave.