Como Usar LLM Local no Cursor IDE e Blindar seu Homelab

O Cursor liberou suporte nativo aos modelos da xAI (Grok), e as comunidades de desenvolvimento foram rápidas nos elogios. Muita gente comentando sobre respostas rápidas, boas sugestões de refatoração e agilidade para interpretar regras de negócio complexas.

Para quem desenvolve front-end ou escreve scripts isolados em Python, avaliar se o cursor ide modelos xai vale a pena faz todo sentido na prática. O problema surge quando você gerencia homelabs, clusters em VPS ou pilhas de containers no Docker.

Ao apontar um editor voltado para inteligência artificial para o seu repositório de infraestrutura, ele não lê apenas o arquivo que está aberto na tela. O Cursor indexa o workspace inteiro para montar o contexto dos prompts. Isso significa que faixas de sub-rede internas, configurações de túneis WireGuard, regras dinâmicas do Traefik e arquivos .env locais podem ser empacotados e enviados diretamente para os servidores da xAI na nuvem.

Veja a seguir o impacto real dessa integração na sua infraestrutura caseira, como travar o editor para evitar vazamentos e o passo a passo para adotar uma ia para programar self-hosted alternativa cursor, rodando modelos locais no seu próprio hardware via Docker.

Cursor xAI vs. vLLM Self-Hosted: Comparativo Direto

Recurso	Cursor + xAI Nativo (Grok)	vLLM Self-Hosted (Qwen2.5-Coder-14B)
Privacidade dos dados	Código enviado para os servidores da xAI	100% local; nenhum pacote sai da sua rede
Velocidade de geração	Rápida (~80–110 tokens/s)	Rápida em GPUs modernas (~45–70 tokens/s em uma RTX 3090)
Custo inicial	R$ 0 (assinatura do Cursor ou chave de API)	Alto (exige GPU NVIDIA com no mínimo 16 GB de VRAM)
Custo recorrente	~US$ 20/mês ou cobrança por token via API	Apenas energia elétrica (~R$ 15–R$ 30/mês em uso real)
Fricção de configuração	Zero; basta selecionar o Grok no menu	Moderada; exige Docker, drivers NVIDIA e CUDA
Opera sem internet (Air-Gap)	Não	Sim

O perigo invisível: por que as configurações padrão colocam seu homelab em risco

O Cursor cria um índice vetorial do repositório local para responder perguntas levando em conta o projeto inteiro. Ao teclar Cmd+K ou abrir o painel Composer, o editor puxa trechos de arquivos vizinhos para alimentar o prompt do modelo.

Aqui mora a armadilha: .gitignore não é .cursorignore.

Embora o Cursor geralmente respeite o .gitignore durante buscas amplas de arquivos, o motor de indexação em segundo plano ainda pode ler arquivos fora do controle de versão, certificados privados e arquivos de ambiente locais, a menos que você proíba isso explicitamente. Se o seu repositório guarda um arquivo .env com chaves da Cloudflare ou um Compose mapeando /var/run/docker.sock, esses dados podem escorregar direto para os prompts enviados à xAI.

Quando você usa o Composer para perguntar: "Por que meu reverse proxy está falhando no health check?", o Cursor não lê apenas a sua pergunta. Ele analisa abas abertas, alterações recentes no git e arquivos de configuração relacionados. Se sua configuração do Traefik apontar para um diretório interno com credenciais em texto puro, essas linhas sobem como contexto.

Como proteger senhas docker compose cursor ignore

Para manter seus segredos restritos à sua máquina, crie um arquivo .cursorignore na raiz de cada repositório de infraestrutura que você abrir. Encare esse arquivo como uma regra de firewall para o seu código-fonte.

Crie o arquivo no terminal:

bash touch .cursorignore

Adicione estas regras para bloquear configurações sensíveis do homelab:

# Segredos e arquivos de ambiente
.env
.env.*
*.env
*.pem
*.key
*.crt
*.pfx
secrets/
credentials/

# WireGuard, SSH e tuneis VPN
wg*.conf
id_rsa*
id_ed25519*
known_hosts

# Infraestrutura e estado local do Terraform
*.tfstate
*.tfstate.backup
docker-compose.override.yml
acme.json

# Volumes persistentes de bancos de dados e logs
data/
volumes/
*.log
*.sqlite
*.db

Se você gerencia um monorepo com dezenas de manifests compose, dê uma olhada nas opções do editor em Cursor Settings > Features > Codebase Indexing. Você pode checar manualmente quais arquivos estão indexados e desativar o escaneamento automático do repositório se estiver mexendo com configurações sensíveis.

A alternativa local: rodando Qwen2.5-Coder no Docker via vLLM

Se mandar a topologia da sua rede para a xAI está fora de cogitação, você pode apontar o Cursor para o seu próprio hardware.

O editor permite sobrescrever a URL base padrão da OpenAI. Ao subir um container de inferência compatível com essa API no seu computador ou em um servidor do homelab, você ganha autocompletar de código, edição guiada por agentes e chat sem enviar um único pacote para fora da sua rede local.

A melhor opção aberta para essa função hoje é o Qwen2.5-Coder-14B-Instruct. Em testes práticos de refatoração, a versão de 14 bilhões de parâmetros entrega um trabalho equivalente ao de modelos comerciais de nuvem na escrita de YAML, bash, Python e sintaxe do Docker. Com quantização GPTQ (4-bit), ele roda com folga em uma GPU NVIDIA com 16 GB de VRAM (como RTX 3090, 4090 ou uma RTX 4000 Ada).

Pré-requisitos do host

Antes de subir o container para aprender como rodar qwen coder no docker, confirme se a sua máquina tem a pilha de drivers configurada:

GPU NVIDIA com no mínimo 16 GB de VRAM (24 GB recomendado para contexto acima de 8k).
NVIDIA Container Toolkit (nvidia-docker2) instalado e funcional.
Drivers compatíveis com CUDA 12.4 ou superior instalados no host.
Docker Compose v2.20 ou mais recente.
Pelo menos 30 GB de espaço livre em disco NVMe para o cache dos pesos do modelo.

Teste o repasse da GPU para o Docker antes de baixar o motor de inferência:

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Se o comando retornar o nome da sua placa e a versão do driver, o daemon do Docker está pronto para a tarefa.

O arquivo Docker Compose

Para configurar vllm docker para cursor, crie um diretório de trabalho chamado local-coder e abra o arquivo do Compose:

mkdir -p ~/local-coder && cd ~/local-coder
nano docker-compose.yml

Cole a configuração abaixo:

services:
  vllm:
    image: vllm/vllm-openai:v0.6.4.post1
    container_name: vllm-coder
    runtime: nvidia
    restart: unless-stopped
    ipc: host
    shm_size: '16gb'
    ports:
      # Amarra estritamente ao loopback para impedir acessos sem autenticacao pela rede local
      - "127.0.0.1:8000:8000"
    environment:
      - HUGGING_FACE_HUB_TOKEN=
    volumes:
      - /opt/huggingface_cache:/root/.cache/huggingface
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model Qwen/Qwen2.5-Coder-14B-Instruct-GPTQ-Int4
      --quantization gptq
      --dtype half
      --max-model-len 8192
      --gpu-memory-utilization 0.90
      --enforce-eager
      --port 8000

Inicie o serviço em segundo plano:

docker compose up -d

Acompanhe os logs para conferir o download dos pesos e a inicialização:

docker compose logs -f vllm

No primeiro boot, o vLLM baixa cerca de 9 GB de arquivos quantizados do Hugging Face para /opt/huggingface_cache. Assim que os logs mostrarem Application startup complete, o vLLM estará pronto para receber requisições em http://127.0.0.1:8000/v1.

Validando o endpoint com cURL

Antes de abrir as opções do Cursor, faça uma chamada de teste no terminal para confirmar que o servidor local está respondendo:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-Coder-14B-Instruct-GPTQ-Int4",
    "messages": [
      {"role": "system", "content": "You are a Linux sysadmin."},
      {"role": "user", "content": "Write a one-line bash command to find files over 500MB in /var/log."}
    ],
    "temperature": 0.2
  }'

Se a resposta em JSON trouxer o comando correto (como find /var/log -type f -size +500M), seu ambiente local está operando perfeitamente.

Conectando o Cursor ao container local

Veja como usar llm local no cursor ide para contornar totalmente os servidores em nuvem:

Abra o Cursor e use o atalho Ctrl+, (ou Cmd+, no macOS) para acessar as Settings.
Clique na aba Models no menu lateral.
Localize a seção OpenAI API Key e ative o botão Override OpenAI Base URL.
Defina a Base URL como: http://127.0.0.1:8000/v1
No campo OpenAI API Key, digite qualquer valor fictício (por exemplo: sk-local-homelab-token). O vLLM ignora a chave por padrão, a não ser que você passe a flag --api-key.
Clique em Add Model e digite o identificador idêntico ao informado no Compose: Qwen/Qwen2.5-Coder-14B-Instruct-GPTQ-Int4.
Desative os modelos padrão da lista (como claude-3-5-sonnet, gpt-4o e grok-beta) para garantir que suas consultas nunca caiam em endpoints externos por engano.

Economia de tokens: fatura da API vs. conta de luz

Antes de reservar uma GPU dedicada para geração de código, vale colocar na ponta do lápis a diferença financeira entre assinaturas de nuvem e consumo de energia elétrica.

APIs comerciais cobram entre US$ 2,00 e US$ 10,00 por milhão de tokens, dependendo da proporção entre tokens de entrada (prompts) e de saída (código gerado). Como assistentes de IDE no formato do Composer enviam contextos extensos (arquivos abertos, árvores de pastas, diffs do git), uma única tarde de trabalho consome fácil 500.000 tokens. Se você programa quatro horas por dia, pode queimar de 2 a 4 milhões de tokens por semana. Na cobrança por uso de API, isso representa entre US$ 15 e US$ 40 todo mês.

Compare esse cenário aos gastos de uma RTX 3090 em um servidor local:

Consumo em repouso (Idle): Em espera, uma RTX 3090 consome entre 15W e 20W. Ligada 24 horas por dia com tarifas médias de energia no Brasil (em torno de R$ 0,85 a R$ 1,00 por kWh), o modo ocioso acrescenta cerca de R$ 10 a R$ 15 por mês na sua conta.
Picos durante a inferência: Durante a geração de código, o consumo sobe para a faixa de 300W a 350W. Só que cada resposta leva poucos segundos. Se você fizer 150 requisições em um dia com média de 4 segundos cada, a placa trabalha em carga máxima por apenas 10 minutos diários. Isso consome aproximadamente 0,05 kWh por dia — menos de R$ 2,00 por mês em uso efetivo.
Custo do hardware: Uma RTX 3090 de 24 GB usada custa entre R$ 4.500 e R$ 6.000 no mercado nacional de usados.

Se o seu objetivo for gastar o mínimo de dinheiro no curto prazo, a assinatura de US$ 20 do Cursor é muito mais barata do que comprar uma placa dedicada. O ponto é que o preço por token não inclui a soberania sobre os seus dados. Para quem roda automações e gerencia homelabs privados, o investimento na GPU não é gasto com comodidade; é uma barreira de segurança que impede que chaves privadas e mapas de rede parem em servidores de terceiros.

Armadilhas comuns para ficar de olho

Mesmo quem já tem bastante experiência administrando sistemas esbarra em detalhes chatos ao rodar LLMs locais integradas a editores. Fique atento a estes quatro pontos:

1. O erro de memória compartilhada sem `ipc: host`

O PyTorch e o vLLM usam memória compartilhada para trocar tensores entre threads com velocidade. O Docker cria containers com uma alocação padrão minúscula de 64 MB para memória compartilhada (/dev/shm). Se você esquecer a diretiva ipc: host ou não declarar shm_size: '16gb', o container vai falhar imediatamente com um erro do tipo Bus error (core dumped) assim que o Cursor mandar um prompt com múltiplos arquivos passando de 2.048 tokens.

2. Expor a porta 8000 na rede local sem querer

No manifest do Docker Compose mostrado acima, o bind de portas foi definido estritamente para o loopback:

ports:
  - "127.0.0.1:8000:8000"

Se você escrever apenas "8000:8000", o Docker vai expor a porta em 0.0.0.0. Isso abre um endpoint de API sem senha para toda a sua rede local. Qualquer máquina na mesma faixa de IP poderá fazer requisições, jogar o uso da sua GPU para 100% e potencialmente ler dados em cache na VRAM. Se o seu motor de inferência rodar em um servidor dedicado sem tela (headless) e não no computador de trabalho, faça o bind no IP privado de uma VPN mesh (como WireGuard ou Tailscale) em vez de liberar para todas as interfaces.

3. Falta de memória na placa por excesso de contexto (OOM)

A flag --max-model-len 8192 no comando do Compose limita a janela máxima de tokens. O Qwen2.5-Coder suporta até 32.768 tokens, mas usar --max-model-len 32768 aloca uma área enorme de cache de Chaves/Valores (KV Cache) na VRAM logo na inicialização. Em placas de 16 GB ou 24 GB, isso consome o espaço livre para tensores dinâmicos, provocando erros de falta de memória (Out Of Memory) durante respostas compridas. Mantenha o teto em 8.192 tokens, a menos que você trabalhe com múltiplas GPUs dividindo a carga.

4. Confiar cegamente no "Modo de Privacidade"

Tanto o Cursor quanto os provedores de modelos proprietários oferecem opções de privacidade pensadas para evitar que seus códigos sejam usados no treinamento de modelos futuros. Essa medida é bem-vinda, mas ela não impede que seu código passe pelos servidores do provedor, fique temporariamente retido em logs de tráfego ou seja afetado por políticas internas de retenção. Se a sua regra interna proíbe que arquivos de infraestrutura saiam da rede local, um botão de privacidade em software não resolve o problema.

Perguntas Frequentes (FAQ)

O Cursor envia código privado e arquivos do Docker Compose para a xAI?

Sim. Ao selecionar um modelo da xAI (como o Grok) no Cursor, pedaços do seu código, arquivos abertos e a estrutura de pastas são empacotados em prompts e transmitidos para os servidores da xAI para montar a resposta. Para evitar que arquivos como stacks Compose, certificados e arquivos .env sejam lidos, você precisa bloqueá-los dentro de um arquivo .cursorignore.

Como configurar o `.cursorignore` para evitar o vazamento de credenciais?

Crie um arquivo chamado .cursorignore na raiz do seu projeto. A sintaxe de regras é idêntica à do .gitignore. Bloqueie arquivos sensíveis como .env*, *.pem, *.key, docker-compose.override.yml, *.tfstate e qualquer pasta de volumes persistentes ou bancos de dados.

Como usar LLM local no Cursor IDE?

Suba um servidor de inferência (como vLLM ou Ollama) que exponha uma API compatível com o padrão da OpenAI. No Cursor, abra Settings > Models, ative a opção Override OpenAI Base URL e insira o endereço do serviço (como http://127.0.0.1:8000/v1). Digite qualquer texto no campo da API key, adicione o identificador exato do modelo e selecione-o como ativo.

O Qwen 2.5 Coder local via vLLM entrega um resultado comparável aos modelos da xAI?

Para demandas cotidianas de homelab e DevOps — como criar Dockerfiles, debugar units do systemd, ajustar Compose files e criar scripts em Python ou Go —, o Qwen2.5-Coder-14B entrega um resultado muito próximo aos modelos de nuvem. Modelos comerciais como o Grok levam vantagem em refatorações complexas que cruzam milhares de linhas de código simultâneas, mas o Qwen dá conta de automações de infraestrutura sem comprometer a sua privacidade.

Dá para rodar essa estrutura em um Mac Apple Silicon em vez de uma GPU NVIDIA?

Sim. O vLLM é desenhado com foco em hardware NVIDIA e CUDA, mas você consegue o mesmo fluxo no macOS usando o Ollama ou o MLX. Em um Mac com memória unificada (como modelos M2/M3 Pro ou Max com 32 GB de RAM ou mais), rode ollama run qwen2.5-coder:14b. Depois, aponte a Base URL da OpenAI no Cursor para http://127.0.0.1:11434/v1 para rodar as inferências direto pelo framework Metal da Apple.

Veredito

A integração nativa da xAI no Cursor entrega uma velocidade impressionante de geração e funciona muito bem para projetos de código aberto ou testes rápidos. O ponto de atenção é que repositórios de homelab guardam os mapas de acesso de toda a sua rede interna. Antes de deixar qualquer modelo externo vasculhar seus arquivos, reserve alguns minutos para criar um .cursorignore bem amarrado.

Se manter seus dados 100% dentro de casa for indispensável para você, monte a stack com vLLM em uma GPU local. A velocidade de resposta será um pouco menor do que nos grandes datacenters, mas as suas credenciais, chaves e topologias de rede nunca vão cruzar os limites do seu firewall.

Relacionados neste cluster

/pt/posts/como-isolar-containers-docker-seguranca/
/pt/posts/como-transformar-mac-mini-em-servidor-caseiro/