DeepSeek-TUI: Setup e Execução

Acabei de passar umas duas horas configurando o DeepSeek-TUI do zero em três ambientes diferentes — macOS com Apple Silicon, Linux x64 e WSL no Windows. O que aprendi nesse processo é o que está aqui.

Uma coisa antes de começar: o DeepSeek-TUI instala dois binários obrigatórios. A maioria das pessoas trava na instalação por não saber disso. Vou cobrir isso direto.

O que você vai ter funcionando no final

• DeepSeek-TUI rodando com um modelo V4 real (Pro ou Flash, sua escolha)
• Uma sessão Plan completa — explorando um repositório sem escrever nenhum arquivo
• Uma sessão Agent com gates de aprovação de tool call
• Uma sessão YOLO com auto-approve (e uma compreensão clara de quando não usar)
• Pelo menos uma skill instalada e um servidor MCP validado

Pré-requisitos

Rust 1.85+ (para o caminho via Cargo) ou Node.js 18+ (para o caminho via npm)

rustc --version
# Precisa: rustc 1.85.0 ou posterior
# Se estiver faltando ou desatualizado:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Se você prefere npm ao invés de compilar do código-fonte, Node.js 18+ é suficiente. O pacote npm baixa binários pré-compilados do GitHub Releases — você não vai compilar nada.

Chave de API do DeepSeek

Crie uma conta em platform.deepseek.com, adicione crédito e copie sua chave de API. O depósito mínimo é $5. Deixe a chave à mão — você vai precisar dela na etapa de autenticação.

Alternativas se você não quiser usar a API do DeepSeek diretamente: NVIDIA NIM e Fireworks AI hospedam o V4. Pra self-hosted, SGLang funciona bem. Cobrindo isso na seção de Providers.

Sobre terminais

macOS/Linux: qualquer terminal moderno funciona. O TUI usa alternate-screen mode e ocupa a tela inteira.

WSL: suportado. Use um terminal que lide bem com alternate-screen — o Windows Terminal funciona bem; variantes antigas do ConEmu podem ter problemas de renderização.

PowerShell/Windows nativo: suportado a partir do v0.8.8. Instale via Scoop (scoop install deepseek-tui) ou baixe os binários diretamente.

Caminho A — Cargo (os dois crates são necessários)

Esse é o caminho de compilação a partir do código-fonte. Demora mais, mas gera binários otimizados pro seu ambiente exato.

# Passo 1: instala o dispatcher (fornece o comando `deepseek`)
cargo install deepseek-tui-cli --locked

# Passo 2: instala o runtime (fornece o comando `deepseek-tui`)
cargo install deepseek-tui --locked

# Verifique que os dois estão no seu PATH:
deepseek --version
deepseek-tui --version

Não pule o --locked. Ele fixa as versões das dependências no lockfile. Sem ele, o Cargo pode puxar dependências transitivas incompatíveis que compilam mas se comportam mal em runtime.

Por que os dois binários são necessários (explicando o MISSING_COMPANION_BINARY)

deepseek (de deepseek-tui-cli) é o dispatcher: cuida de autenticação, config, seleção de modelo, e então delega pro deepseek-tui o runtime do agente e o TUI. Se você rodar deepseek sem deepseek-tui no PATH:

Error: MISSING_COMPANION_BINARY
The `deepseek-tui` binary was not found. Both binaries must be installed.

Instalar só o deepseek-tui sem o dispatcher produz o reverso — você consegue abrir o binário do TUI diretamente mas perde o entrypoint limpo, o gerenciamento de autenticação e o repasse de config. Instale os dois.

Caminho B — npm

O caminho npm baixa binários Rust pré-compilados do GitHub Releases. Sem compilação. Requer Node.js 18+ na instalação, mas não em runtime — os binários são executáveis nativos.

npm install -g deepseek-tui

O script de postinstall baixa o par correto de binários pra sua plataforma, verifica um manifesto SHA-256 e coloca os dois — deepseek e deepseek-tui — no seu PATH.

Quando npm é preferível

• Você não tem Rust instalado e não quer instalar
• Você está em uma máquina onde a compilação é lenta ou restrita
• Você quer o caminho mais rápido para uma instalação funcional

Nota para a China continental: Adicione o mirror do registry para evitar downloads lentos:

npm install -g deepseek-tui --registry=https://registry.npmmirror.com

Caminho C — Binários pré-compilados

Baixe diretamente do GitHub Releases. Os dois binários — deepseek e deepseek-tui — precisam ser baixados pra sua plataforma e colocados no mesmo diretório no PATH.

Plataformas disponíveis: Linux x64, Linux ARM64, macOS x64, macOS ARM64 (Apple Silicon), Windows x64.

Verificação SHA-256

# Baixe o manifesto junto com seus binários:
curl -L -o /tmp/deepseek-artifacts-sha256.txt \
  https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-artifacts-sha256.txt

# Linux:
( cd ~/.local/bin && sha256sum -c /tmp/deepseek-artifacts-sha256.txt --ignore-missing )

# macOS:
( cd ~/.local/bin && shasum -a 256 -c /tmp/deepseek-artifacts-sha256.txt --ignore-missing )

URL do Mirror (DEEPSEEK_TUI_RELEASE_BASE_URL)

Se o GitHub Releases estiver lento na sua rede:

export DEEPSEEK_TUI_RELEASE_BASE_URL=https://seu-mirror.exemplo.com/releasesnpm install -g deepseek-tui   # o downloader do npm respeita esta variável de ambiente

Primeira autenticação

# Configure sua chave de API:
deepseek auth set --provider deepseek --api-key "SUA_CHAVE_DEEPSEEK"

# Verifique se está armazenada:
deepseek auth status

Onde fica o arquivo de configuração

~/.deepseek/config.toml

O arquivo de configuração é compartilhado entre o dispatcher e o runtime do TUI. O comando deepseek login --api-key ... escreve no campo api_key, que é lido diretamente pelo deepseek-tui.

Alternativa por variável de ambiente

Se você prefere não gravar credenciais em disco:

export DEEPSEEK_API_KEY="sua-chave"
deepseek   # pega a env var automaticamente

Pra pipelines CI/CD ou ambientes Docker, injeção via env var é a abordagem certa. O caminho do config file é baseado no home do usuário e não existe por padrão em contextos containerizados.

Escolhendo um provider

DeepSeek direto (padrão)

deepseek auth set --provider deepseek --api-key "SUA_CHAVE"
deepseek   # usa api.deepseek.com por padrão

NVIDIA NIM

deepseek auth set --provider nvidia-nim --api-key "SUA_CHAVE_NVIDIA"
deepseek --provider nvidia-nim

O NIM exige uma URL base específica em algumas configurações. Consulte o arquivo docs/CONFIGURATION.md no repositório para as configurações específicas do NIM.

Fireworks AI

deepseek auth set --provider fireworks --api-key "SUA_CHAVE_FIREWORKS"
deepseek --provider fireworks --model accounts/fireworks/models/deepseek-v4-pro

SGLang self-hosted

# SGLang roda local — sem chave de API por padrão
deepseek --provider sglang   # assume localhost:30000/v1

Para usar uma URL base personalizada do SGLang, configure-a no arquivo ~/.deepseek/config.toml na seção [profiles.sglang].

V4-Pro vs V4-Flash — qual usar

deepseek --model deepseek-v4-pro     # flagship, custo maior, raciocínio mais profundo
deepseek --model deepseek-v4-flash   # mais rápido, mais barato, raciocínio mais leve

Você também pode definir o padrão na config:

# ~/.deepseek/config.toml
default_text_model = "deepseek-v4-flash"

Quando usar cada modelo por padrão

Use o V4-Flash como padrão para:

• Sessões exploratórias, onde você ainda está descobrindo o que perguntar
• Loops agenticos de alto volume, onde o custo por execução é importante
• Sub-agentes filhos do RLM (o Flash é o padrão do RLM e isso é intencional)

Mude para o V4-Pro quando:

• Estiver fazendo refatorações complexas em múltiplos arquivos, onde a profundidade de raciocínio é crítica
• Tarefas que falharam no Flash por suposições incorretas
• Sessões de arquitetura e design, onde a qualidade e completude valem mais que o custo

Rodando sua primeira sessão em cada modo

Plan mode — explorando um repo sem escrever nada

Plan mode restringe o agente a operações de leitura. Sem escrita de arquivos, sem execução de shell.

deepseek plan "Explique a estrutura desse repo e identifique os principais entry points"

Ou abra o TUI e mude dentro da sessão:

deepseek   # abre o TUI
# depois pressione: Shift+Tab pra alternar Plan mode

Em Plan mode, o agente lê arquivos, faz buscas na codebase e retorna uma análise estruturada. Nada muda na sua working tree. Use isso como primeira passagem antes de fazer um run Agent.

Agent mode — loop padrão com aprovações

Agent mode é o padrão. Cada tool call que modifica estado requer sua aprovação explícita.

deepseek   # abre em Agent mode por padrão

Dentro do TUI, você vai ver cada tool call proposto antes de ser executado:

┌─ Tool Call ───────────────────────────────────┐
│ bash: git diff HEAD~1 --stat                  │
│ [A]pprove  [S]kip  [E]dit  [Q]uit             │
└───────────────────────────────────────────────┘

Uma primeira sessão mínima:

> Leia o README e resuma o propósito do projeto em três frases

O agente vai chamar read_file no README. Você vai ver o prompt de aprovação. Pressione A. O agente responde com o resumo. Nenhum arquivo é escrito.

YOLO mode — quando (e quando não) usar

YOLO mode aprova automaticamente todos os tool calls sem prompts.

deepseek --yolo   # abre em YOLO mode

Quando YOLO é apropriado: workspaces confiáveis onde você já revisou o escopo da tarefa, o agente está executando algo bem definido que você já viu funcionar, e você quer execução sem interrupção.

Quando YOLO não é apropriado: qualquer tarefa envolvendo git commits, deleção de arquivos, requisições de rede, ou comandos shell com side effects que você não revisou. YOLO pula o gate de aprovação completamente — se o agente decidir fazer rm -rf em alguma coisa ou fazer push de um commit, vai fazer. Um bug fix do v0.8.8 tratou especificamente o YOLO aprovando automaticamente git -C ... sem verificações de workspace trust. Essa classe de bug vale lembrar quando rodar YOLO em tarefas desconhecidas.

Adicionando Skills e servidores MCP

Instalando uma community skill

# Instala do GitHub (sem serviço backend necessário):
/skill install github:owner/repo-name

# Lista skills instaladas:
/skills

# Ativa uma skill pra sessão atual:
/skill minha-skill

O DeepSeek-TUI também descobre skills automaticamente de diretórios do workspace. Se você tem um diretório .claude/skills/ de uso do Claude Code, ele vai encontrar esses arquivos também.

Configurando um servidor MCP

# Inicializa a estrutura de diretórios MCP:
deepseek-tui mcp init

# Valida a conexão com um servidor MCP:
/mcp validate

Servidores MCP são configurados em ~/.deepseek/config.toml em [mcp.servers]. Depois de adicionar uma entrada, reinicie o TUI e rode /mcp validate pra confirmar a conexão.

Erros comuns e como resolver

MISSING_COMPANION_BINARY

Error: MISSING_COMPANION_BINARY

Instale o binário que está faltando. Se deepseek está instalado mas não deepseek-tui:

cargo install deepseek-tui --locked
# ou: npm install -g deepseek-tui  (reinstala os dois)

Os dois binários precisam estar no mesmo diretório ou os dois no PATH. Instalar via npm cuida disso automaticamente; Cargo instala em ~/.cargo/bin/ por padrão, então os dois ficam no lugar certo.

aarch64 / arm64 mismatch em versões antigas

Error: Unsupported architecture: arm64

Isso afeta v0.8.7 e anteriores, que não publicavam binários pré-compilados pra Linux ARM64. Corrija atualizando pra v0.8.8 ou posterior, ou compile do código-fonte:

git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI
cargo install --path crates/cli --locked
cargo install --path crates/tui --locked

Nota: confirme no CHANGELOG atual — esta ressalva está correta até a v0.8.8; versões mais recentes podem ter expandido o suporte a binários pré-compilados.

Chave de API não detectada em subshells

Se você definir DEEPSEEK_API_KEY no seu shell e ele não for reconhecido quando o TUI for iniciado:

# Verifique se a variável está exportada (não só definida):
echo $DEEPSEEK_API_KEY

# Se vazio, exporte corretamente:
export DEEPSEEK_API_KEY="sua-chave"

# Ou use o comando auth pra gravar na config (persiste entre sessões):
deepseek auth set --provider deepseek --api-key "sua-chave"

A abordagem via config file é mais confiável entre sessões de terminal, shells e editores que abrem seus próprios subprocessos.

Bug de arch-name no self-updater (aviso para v0.8.x)

O self-updater em versões em torno do v0.8.7 usava constantes de arquitetura brutas do Rust (aarch64, x86_64) ao invés da convenção de naming dos release assets (arm64, x64). Isso fazia o self-update falhar com erro de "binary not found" em sistemas ARM64. O fix foi no v0.8.8.

Se deepseek update falha com erro de resolução de asset, atualize manualmente rodando seu comando de instalação original ou baixando do GitHub Releases diretamente.

FAQ

Preciso mesmo dos dois binários deepseek e deepseek-tui?

Sim. Não são intercambiáveis. deepseek é o dispatcher (autenticação, config, seleção de modelo) e deepseek-tui é o runtime (renderização do TUI, loop do agente, execução de ferramentas). O dispatcher delega explicitamente pro runtime; rodar qualquer um dos dois sozinho falha na inicialização.

Posso apontar pra OpenAI ou Anthropic?

Não. Os providers suportados — DeepSeek direto, NVIDIA NIM, Fireworks, SGLang — todos servem modelos DeepSeek. A ferramenta não é um wrapper genérico compatível com OpenAI. Se você quer Claude ou GPT-5 como backend, use Claude Code ou um agente agnóstico de modelo.

Como troco de modelo no meio de uma sessão?

Via flag --model na inicialização, ou reiniciando com um modelo diferente. O TUI não expõe um comando /model pra trocar o modelo ativo no meio de uma sessão sem reiniciar. Use V4-Flash como padrão e reinicie com --model deepseek-v4-pro quando uma tarefa precisar de raciocínio mais profundo.

Onde ficam as sessões e snapshots?

~/.deepseek/sessions/     # metadados e transcrições de sessão
~/.deepseek/state/        # estado de runtime, incluindo checkpoints
~/.deepseek/memory/       # memória de projeto (sobrevive a resets de contexto)

Pra retomar uma sessão anterior: deepseek-tui resume. Pra fazer fork de uma sessão a partir de um snapshot: deepseek-tui fork.

Funciona no terminal integrado do VS Code?

Sim, com ressalvas. O TUI em alternate-screen renderiza corretamente no terminal integrado do VS Code no macOS e Linux. Windows via terminal integrado do VS Code funciona mas pode ter conflitos de scroll capture. Se o TUI captura mouse input por padrão (tui.mouse_capture = true) e você quer usar o scrollback do terminal do VS Code, desative:

# ~/.deepseek/config.toml
[tui]
mouse_capture = false

Ou passe --no-mouse-capture na inicialização.