Por que usar o Modo Servidor?
Centralização
Um único servidor com API keys configuradas atende múltiplos clientes
Segurança
As chaves de API ficam no servidor, nunca expostas nos terminais clientes
Flexibilidade
Clientes podem usar suas próprias credenciais (API key ou OAuth) se desejarem
Performance
Comunicação via gRPC com suporte a TLS e streaming progressivo
Iniciando o Servidor
Flags Disponíveis
| Flag | Descrição | Padrão | Env Var |
|---|---|---|---|
--port | Porta do servidor gRPC | 50051 | CHATCLI_SERVER_PORT |
--token | Token de autenticação (vazio = sem auth) | "" | CHATCLI_SERVER_TOKEN |
--tls-cert | Arquivo de certificado TLS | "" | CHATCLI_SERVER_TLS_CERT |
--tls-key | Arquivo de chave TLS | "" | CHATCLI_SERVER_TLS_KEY |
--provider | Provedor de LLM padrão | Auto-detectado | LLM_PROVIDER |
--model | Modelo de LLM padrão | Auto-detectado | |
--metrics-port | Porta HTTP para métricas Prometheus (0 = desabilita) | 9090 | CHATCLI_METRICS_PORT |
Flags de Fallback (opcionais)
| Flag | Descrição | Padrão | Env Var |
|---|---|---|---|
--fallback-providers | Lista de provedores separados por vírgula para failover | "" | CHATCLI_FALLBACK_PROVIDERS |
--fallback-max-retries | Tentativas por provedor antes de avançar | 2 | CHATCLI_FALLBACK_MAX_RETRIES |
--fallback-cooldown-base | Cooldown base após falha | 30s | CHATCLI_FALLBACK_COOLDOWN_BASE |
--fallback-cooldown-max | Cooldown máximo (backoff exponencial) | 5m | CHATCLI_FALLBACK_COOLDOWN_MAX |
Flag MCP (opcional)
| Flag | Descrição | Padrão | Env Var |
|---|---|---|---|
--mcp-config | Arquivo JSON de configuração MCP | "" | CHATCLI_MCP_CONFIG |
Prometheus Metrics
O servidor expõe métricas Prometheus emhttp://localhost:9090/metrics por padrão. As métricas incluem:
- gRPC:
chatcli_grpc_requests_total,chatcli_grpc_request_duration_seconds,chatcli_grpc_in_flight_requests - LLM:
chatcli_llm_requests_total,chatcli_llm_request_duration_seconds,chatcli_llm_errors_total - Watcher:
chatcli_watcher_collection_duration_seconds,chatcli_watcher_alerts_total,chatcli_watcher_pods_ready - Session:
chatcli_session_active_total,chatcli_session_operations_total - Server:
chatcli_server_uptime_seconds,chatcli_server_info - Go runtime: goroutines, memória, GC (via GoCollector/ProcessCollector)
--metrics-port 0.
Variáveis de Segurança
| Env Var | Descrição | Padrão |
|---|---|---|
CHATCLI_GRPC_REFLECTION | Habilita gRPC reflection para debugging. Mantenha desabilitado em produção. | false |
CHATCLI_DISABLE_VERSION_CHECK | Desabilita verificação automática de versão no startup. | false |
Flags do K8s Watcher (opcionais)
| Flag | Descrição | Padrão | Env Var |
|---|---|---|---|
--watch-config | Arquivo YAML multi-target | "" | CHATCLI_WATCH_CONFIG |
--watch-deployment | Deployment único (legado) | "" | CHATCLI_WATCH_DEPLOYMENT |
--watch-namespace | Namespace do deployment | "default" | CHATCLI_WATCH_NAMESPACE |
--watch-interval | Intervalo de coleta | 30s | CHATCLI_WATCH_INTERVAL |
--watch-window | Janela de observação | 2h | CHATCLI_WATCH_WINDOW |
--watch-max-log-lines | Max linhas de log por pod | 100 | CHATCLI_WATCH_MAX_LOG_LINES |
--watch-kubeconfig | Caminho do kubeconfig | Auto-detectado | CHATCLI_KUBECONFIG |
Use
--watch-config para monitorar múltiplos deployments simultaneamente com métricas Prometheus. Veja K8s Watcher para o formato do arquivo YAML.Autenticação do Servidor
- Sem Autenticação
- Com Token
- TLS (HTTPS)
Por padrão, o servidor não exige autenticação. Qualquer cliente pode conectar:
Modos de Credencial
O servidor suporta múltiplos modos de credencial LLM, dando flexibilidade total:1. Credenciais do Servidor (Padrão)
1. Credenciais do Servidor (Padrão)
O servidor usa suas próprias API keys configuradas via variáveis de ambiente:Nenhuma configuração adicional necessária no cliente.
2. Credenciais do Cliente (API Key)
2. Credenciais do Cliente (API Key)
O cliente pode enviar sua própria API key, que o servidor usa em vez das suas:
3. Credenciais do Cliente (OAuth Local)
3. Credenciais do Cliente (OAuth Local)
O cliente pode usar tokens OAuth do auth store local (
~/.chatcli/auth-profiles.json):4. Credenciais StackSpot
4. Credenciais StackSpot
Para o provedor StackSpot, envie as credenciais completas:
5. GitHub Copilot (OAuth Local)
5. GitHub Copilot (OAuth Local)
Para usar GitHub Copilot, faça login via Device Flow e conecte com
--use-local-auth:6. Ollama (Sem Credenciais)
6. Ollama (Sem Credenciais)
Para modelos locais via Ollama, basta informar a URL:
Arquitetura gRPC
O servidor implementa um serviço gRPC com os seguintes RPCs:| RPC | Descrição |
|---|---|
SendPrompt | Envia um prompt e recebe a resposta completa |
StreamPrompt | Envia um prompt e recebe a resposta em chunks progressivos |
InteractiveSession | Streaming bidirecional para sessões interativas |
ListSessions | Lista sessões salvas no servidor |
LoadSession | Carrega uma sessão salva |
SaveSession | Salva a sessão atual |
Health | Health check do servidor |
GetServerInfo | Informações do servidor (versão, provider, modelo, watcher) |
GetWatcherStatus | Status do K8s Watcher (se ativo) |
ListRemotePlugins | Lista plugins disponíveis no servidor |
ListRemoteAgents | Lista agents disponíveis no servidor |
ListRemoteSkills | Lista skills disponíveis no servidor |
GetAgentDefinition | Retorna o conteúdo completo de um agent (markdown + frontmatter) |
GetSkillContent | Retorna o conteúdo completo de uma skill |
ExecuteRemotePlugin | Executa um plugin no servidor e retorna o resultado |
DownloadPlugin | Streaming de download do binário de um plugin |
GetAlerts | Retorna alertas ativos do K8s Watcher (usado pelo Operator) |
AnalyzeIssue | Envia contexto de um Issue ao LLM e retorna análise + ações sugeridas |
gRPC com Múltiplas Réplicas
O gRPC usa conexões HTTP/2 persistentes que, por padrão, fixam em um único pod via kube-proxy. Para cenários com múltiplas réplicas no Kubernetes:- 1 réplica: Service ClusterIP padrão — sem configuração extra necessária
- Múltiplas réplicas: Use um Service headless (
ClusterIP: None) para que o DNS retorne os IPs individuais dos pods, habilitando balanceamento round-robin client-side via resolverdns:///do gRPC - O client do ChatCLI já possui keepalive (ping a cada 10s) e suporte a round-robin integrados
- No Helm chart, habilite
service.headless: truequandoreplicaCount > 1 - No Operator, o headless é ativado automaticamente quando
spec.replicas > 1
Para mais detalhes, veja a documentação do K8s Operator e o deploy com Helm.
Streaming Progressivo
O RPCStreamPrompt divide a resposta em chunks de ~200 caracteres em fronteiras naturais (parágrafos, linhas, frases), proporcionando uma experiência de resposta progressiva no cliente.
RPCs de Descoberta de Recursos
Os RPCsListRemotePlugins, ListRemoteAgents, ListRemoteSkills, GetAgentDefinition, GetSkillContent, ExecuteRemotePlugin e DownloadPlugin permitem que clientes conectados descubram e usem recursos instalados no servidor.
- Plugins: Executados no servidor via
ExecuteRemotePluginou baixados viaDownloadPlugin(streaming binário) - Agents/Skills: Conteúdo markdown transferido ao client via
GetAgentDefinition/GetSkillContentpara composição local de prompts
RPCs da Plataforma AIOps
Os RPCsGetAlerts e AnalyzeIssue são usados pelo Operator AIOps para alimentar o pipeline autônomo de remediação.
GetAlerts
Retorna os alertas ativos detectados pelo K8s Watcher:AnalyzeIssue
Envia o contexto de um Issue ao LLM e retorna análise estruturada com ações sugeridas:Integração com K8s Watcher
Quando o servidor é iniciado com--watch-config ou --watch-deployment, o K8s Watcher monitora continuamente os deployments e injeta automaticamente o contexto Kubernetes em todos os prompts dos clientes remotos.
- Single-Target (legado)
- Multi-Target (recomendado)