Como instalar e configurar o DeepSeek Harness com a API do Apiário Dev

O DeepSeek Harness (dsh) é o harness oficial da DeepSeek: open-source, com a filosofia de que tudo é um plugin e capaz de apontar para qualquer gateway compatível com a API da OpenAI. Ou seja, dá para usá-lo com a API do Apiário Dev e aproveitar um catálogo com cerca de 31 modelos, preço em reais, pagamento pré-pago no PIX e uma única chave.

Neste tutorial você vai instalar o dsh via npx, entrar na Web UI, adicionar o Apiário Dev como custom provider, deixar o próprio harness descobrir os modelos disponíveis e rodar o primeiro prompt. Antes de começar: o dsh está em developer preview e muda rápido — quando bater dúvida, a documentação oficial pode te ajudar.

Prefere assistir? O vídeo abaixo tem o mesmo caminho em movimento.

O que é o DeepSeek Harness e por que usar um provider nacional

O dsh segue a ideia de que Agent = Model + Harness. O modelo é o cérebro; o harness é tudo em volta — ferramentas, skills, interface e a forma como o agente planeja e executa. Tudo isso é plugável, então você troca o modelo sem trocar a experiência.

Ele já vem com presets prontos que você ativa em uma linha: Standard, PTC, Minimal e Creator. Não vamos aprofundar aqui — a ideia é só situar você de que existe mais de um jeito de rodar o mesmo agente.

Por que apontar o dsh para o Apiário Dev?

• Protocolo que ele entende: o Apiário Dev expõe openai-completions, um dos protocolos que o DSH suporta nativamente.
• Discovery pronto: GET /v1/models já responde no formato esperado, então o botão Fetch available models funciona sem gambiarra.
• Sem compat extra para roles: o Apiário Dev normaliza developer → system do lado do gateway, então você não precisa de configuração adicional só para isso.
• Cobrança previsível: preço em BRL e chave pré-paga, sem surpresa de câmbio.

Se você já conectou o Apiário Dev a outro harness, o gesto vai parecer familiar — o tutorial do OpenCode segue a mesma lógica. E o catálogo completo, com os valores vigentes, está no painel de modelos.

Instalando o DSH e entrando na Web UI

O pré-requisito é Node ^22.19.0 || >=24.0.0 — dá para confirmar no package.json do repositório oficial. Com o Node certo, o comando é um só:

$ npx @deepseek-ai/dsh web
Need to install the following packages:
  @deepseek-ai/dsh@<versão>
Ok to proceed? (y)

O npx pergunta se pode baixar o pacote na primeira execução; responda y. O comando web é um atalho para --profile web, o preset que sobe a interface gráfica em http://127.0.0.1:3080.

A confirmação do npx na primeira execução: responda y e a Web UI sobe.

Ao abrir a interface, um modal pede uma API key da DeepSeek. Não é essa a chave que queremos. Escolha Configure later — a chave do Apiário Dev tem outro formato e vai no passo seguinte.

Configure later: a chave do Apiário Dev entra depois, como custom provider.

Fecha o modal e o dsh pede para você escolher um workspace. O diretório onde você iniciou o comando é o workspace root padrão. Escolha uma pasta de projeto (não uma pasta global) e confirme — é dentro dela que o agente vai ler e escrever arquivos. A sessão só destrava depois dessa escolha.

Configurando o Apiário Dev como custom provider

Com a interface aberta, clique na engrenagem de Settings e vá até a aba Models.

Settings → Models é onde vive a configuração de providers.

Ali existe a entrada Add a custom provider. É esse o caminho, porque o Apiário Dev fala openai-completions — exatamente o protocolo que o formulário espera.

Add a custom provider: o ponto de partida para plugar o Apiário Dev.

Preencha os campos assim:

Campo	Valor
Provider ID	apiario
Display name	Apiário Dev
Base URL	https://api.apiario.dev/v1
API protocol	openai-completions
API key	sua chave sk-...

O formulário preenchido: note o /v1 no fim da Base URL.

⚠️ O Provider ID é permanente — escolha bem antes de criar. Já a API key é write-only: a interface não mostra a chave depois de salva. Ela vai para ~/.dsh/.credentials.yaml, e não para o settings.yaml.

Com o formulário preenchido, clique em Fetch available models. O harness chama o GET /v1/models do Apiário Dev e lista o catálogo — bem mais amplo que só modelos DeepSeek.

Fetch available models: o próprio harness descobre o catálogo do Apiário Dev.

O modal Choose models to add deixa você marcar o que quer. Selecione os que pretende usar e confirme em Add selected — esse print mostra a seleção sendo feita.

Marque os modelos e confirme em Add selected.

Por fim, clique em Create provider. O provider apiario passa a aparecer na lista, com os modelos escolhidos prontos para uso.

Create provider: o Apiário Dev entra na lista de providers do DSH.

Primeiro prompt e ajustes avançados

Abra o seletor de modelo do chat e escolha DeepSeek V4.1 Flash (deepseek/deepseek-v4.1-flash) — contexto de 1M tokens e capacidades de texto, function calling, visão e raciocínio. Se aparecer um sufixo como High ao lado do nome, ele é o reasoning effort, não parte do ID.

O modelo final do tutorial: DeepSeek V4.1 Flash.

Agora o teste clássico: pergunte “Quantos arquivos estão nesta pasta?”. O agente deve decidir sozinho usar a ferramenta de shell, listar o workspace e responder.

O agente escolhe a tool de shell sozinho para responder.

Conclusão e próximos passos

npx @deepseek-ai/dsh web sobe a interface; Settings → Models → Add a custom provider com a Base URL da API; Fetch available models, selecione, Create provider. Depois é só escolher o modelo e conversar.

Para começar com o Apiário Dev:

• Crie sua conta e gere sua chave de API.
• Confira o catálogo e os preços no painel de modelos.
• Quer o mesmo em outro harness? Veja como usar a API no OpenCode.
• Prefere direto no terminal? O CLI npx apiario é o caminho mais curto.