Pular para o conteúdo principal
O Modo Servidor transforma o ChatCLI em um serviço gRPC de alta performance que pode ser acessado remotamente por qualquer terminal. Isso permite centralizar o acesso a IA em um servidor (bare-metal, VM, Docker ou Kubernetes) e conectar de qualquer lugar.

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
O modo servidor oferece integração nativa com o K8s Watcher para monitoramento de deployments Kubernetes.

Iniciando o Servidor

1

Modo mais simples

Servidor na porta padrão (50051):
chatcli server
2

Com porta e autenticação customizados

chatcli server --port 8080 --token meu-token-secreto
3

Com TLS habilitado

chatcli server --tls-cert cert.pem --tls-key key.pem
4

Com K8s Watcher integrado (opcional)

# Single-target (legado)
chatcli server --watch-deployment myapp --watch-namespace production

# Multi-target + Prometheus metrics
chatcli server --watch-config targets.yaml
5

Com fallback de provedores (opcional)

chatcli server --fallback-providers OPENAI,CLAUDEAI,GOOGLEAI,COPILOT
6

Com MCP (opcional)

chatcli server --mcp-config ~/.chatcli/mcp_servers.json

Flags Disponíveis

FlagDescriçãoPadrãoEnv Var
--portPorta do servidor gRPC50051CHATCLI_SERVER_PORT
--tokenToken de autenticação (vazio = sem auth)""CHATCLI_SERVER_TOKEN
--tls-certArquivo de certificado TLS""CHATCLI_SERVER_TLS_CERT
--tls-keyArquivo de chave TLS""CHATCLI_SERVER_TLS_KEY
--providerProvedor de LLM padrãoAuto-detectadoLLM_PROVIDER
--modelModelo de LLM padrãoAuto-detectado
--metrics-portPorta HTTP para métricas Prometheus (0 = desabilita)9090CHATCLI_METRICS_PORT

Flags de Fallback (opcionais)

FlagDescriçãoPadrãoEnv Var
--fallback-providersLista de provedores separados por vírgula para failover""CHATCLI_FALLBACK_PROVIDERS
--fallback-max-retriesTentativas por provedor antes de avançar2CHATCLI_FALLBACK_MAX_RETRIES
--fallback-cooldown-baseCooldown base após falha30sCHATCLI_FALLBACK_COOLDOWN_BASE
--fallback-cooldown-maxCooldown máximo (backoff exponencial)5mCHATCLI_FALLBACK_COOLDOWN_MAX

Flag MCP (opcional)

FlagDescriçãoPadrãoEnv Var
--mcp-configArquivo JSON de configuração MCP""CHATCLI_MCP_CONFIG

Prometheus Metrics

O servidor expõe métricas Prometheus em http://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)
Para desabilitar, use --metrics-port 0.

Variáveis de Segurança

Env VarDescriçãoPadrão
CHATCLI_GRPC_REFLECTIONHabilita gRPC reflection para debugging. Mantenha desabilitado em produção.false
CHATCLI_DISABLE_VERSION_CHECKDesabilita verificação automática de versão no startup.false
O gRPC reflection está desabilitado por padrão para não expor o schema do serviço em produção. Habilite apenas para debugging local. Veja a documentação de segurança para todas as medidas de hardening.

Flags do K8s Watcher (opcionais)

FlagDescriçãoPadrãoEnv Var
--watch-configArquivo YAML multi-target""CHATCLI_WATCH_CONFIG
--watch-deploymentDeployment único (legado)""CHATCLI_WATCH_DEPLOYMENT
--watch-namespaceNamespace do deployment"default"CHATCLI_WATCH_NAMESPACE
--watch-intervalIntervalo de coleta30sCHATCLI_WATCH_INTERVAL
--watch-windowJanela de observação2hCHATCLI_WATCH_WINDOW
--watch-max-log-linesMax linhas de log por pod100CHATCLI_WATCH_MAX_LOG_LINES
--watch-kubeconfigCaminho do kubeconfigAuto-detectadoCHATCLI_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

Por padrão, o servidor não exige autenticação. Qualquer cliente pode conectar:
chatcli server  # sem --token = acesso livre

Modos de Credencial

O servidor suporta múltiplos modos de credencial LLM, dando flexibilidade total:
O servidor usa suas próprias API keys configuradas via variáveis de ambiente:
export OPENAI_API_KEY=sk-xxx
export LLM_PROVIDER=OPENAI
chatcli server
Nenhuma configuração adicional necessária no cliente.
O cliente pode enviar sua própria API key, que o servidor usa em vez das suas:
chatcli connect servidor:50051 --llm-key sk-minha-chave --provider OPENAI
O cliente pode usar tokens OAuth do auth store local (~/.chatcli/auth-profiles.json):
# Primeiro, faça login OAuth localmente
/auth login anthropic

# Depois, conecte usando as credenciais locais
chatcli connect servidor:50051 --use-local-auth
Para o provedor StackSpot, envie as credenciais completas:
chatcli connect servidor:50051 --provider STACKSPOT \
  --client-id <id> --client-key <key> --realm <realm> --agent-id <agent>
Para usar GitHub Copilot, faça login via Device Flow e conecte com --use-local-auth:
# Primeiro, faça login no GitHub Copilot
/auth login github-copilot

# Conecte usando as credenciais locais
chatcli connect servidor:50051 --use-local-auth --provider COPILOT
Para modelos locais via Ollama, basta informar a URL:
chatcli connect servidor:50051 --provider OLLAMA --ollama-url http://gpu-server:11434

Arquitetura gRPC

O servidor implementa um serviço gRPC com os seguintes RPCs:
RPCDescrição
SendPromptEnvia um prompt e recebe a resposta completa
StreamPromptEnvia um prompt e recebe a resposta em chunks progressivos
InteractiveSessionStreaming bidirecional para sessões interativas
ListSessionsLista sessões salvas no servidor
LoadSessionCarrega uma sessão salva
SaveSessionSalva a sessão atual
HealthHealth check do servidor
GetServerInfoInformações do servidor (versão, provider, modelo, watcher)
GetWatcherStatusStatus do K8s Watcher (se ativo)
ListRemotePluginsLista plugins disponíveis no servidor
ListRemoteAgentsLista agents disponíveis no servidor
ListRemoteSkillsLista skills disponíveis no servidor
GetAgentDefinitionRetorna o conteúdo completo de um agent (markdown + frontmatter)
GetSkillContentRetorna o conteúdo completo de uma skill
ExecuteRemotePluginExecuta um plugin no servidor e retorna o resultado
DownloadPluginStreaming de download do binário de um plugin
GetAlertsRetorna alertas ativos do K8s Watcher (usado pelo Operator)
AnalyzeIssueEnvia 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 resolver dns:/// 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: true quando replicaCount > 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 RPC StreamPrompt 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 RPCs ListRemotePlugins, ListRemoteAgents, ListRemoteSkills, GetAgentDefinition, GetSkillContent, ExecuteRemotePlugin e DownloadPlugin permitem que clientes conectados descubram e usem recursos instalados no servidor.
  • Plugins: Executados no servidor via ExecuteRemotePlugin ou baixados via DownloadPlugin (streaming binário)
  • Agents/Skills: Conteúdo markdown transferido ao client via GetAgentDefinition/GetSkillContent para composição local de prompts

RPCs da Plataforma AIOps

Os RPCs GetAlerts 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:
rpc GetAlerts(GetAlertsRequest) returns (GetAlertsResponse);

message GetAlertsRequest {
  string namespace = 1;     // Filtrar por namespace (vazio = todos)
  string deployment = 2;    // Filtrar por deployment (vazio = todos)
}

message AlertInfo {
  string alert_type = 1;    // HighRestartCount, OOMKilled, PodNotReady, DeploymentFailing
  string deployment = 2;
  string namespace = 3;
  string message = 4;
  string severity = 5;      // critical, warning
  int64 timestamp = 6;
}

AnalyzeIssue

Envia o contexto de um Issue ao LLM e retorna análise estruturada com ações sugeridas:
rpc AnalyzeIssue(AnalyzeIssueRequest) returns (AnalyzeIssueResponse);

message AnalyzeIssueRequest {
  string issue_name = 1;
  string namespace = 2;
  string resource_kind = 3;
  string resource_name = 4;
  string signal_type = 5;
  string severity = 6;
  string description = 7;
  int32 risk_score = 8;
  string provider = 9;
  string model = 10;
}

message SuggestedAction {
  string name = 1;
  string action = 2;
  string description = 3;
  map<string, string> params = 4;
}

message AnalyzeIssueResponse {
  string analysis = 1;
  float confidence = 2;     // 0.0-1.0
  repeated string recommendations = 3;
  string provider = 4;
  string model = 5;
  repeated SuggestedAction suggested_actions = 6;
}

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.
chatcli server --watch-deployment myapp --watch-namespace production
Qualquer usuário conectado pode fazer perguntas sobre os deployments sem configuração adicional:
Conectado ao ChatCLI server (version: 1.0.0, provider: OPENAI, model: gpt-4o)
K8s watcher active: 5 targets (interval: 30s)

> Quais deployments precisam de atenção?
> Analise as métricas HTTP do api-gateway

Variáveis de Ambiente

Todas as variáveis de ambiente usadas pelo ChatCLI local também funcionam no servidor:
# Servidor
CHATCLI_SERVER_PORT=50051
CHATCLI_SERVER_TOKEN=meu-token
CHATCLI_SERVER_TLS_CERT=/path/to/cert.pem
CHATCLI_SERVER_TLS_KEY=/path/to/key.pem

# Segurança
CHATCLI_GRPC_REFLECTION=false
CHATCLI_DISABLE_VERSION_CHECK=false

# LLM
LLM_PROVIDER=CLAUDEAI
ANTHROPIC_API_KEY=sk-ant-xxx
ANTHROPIC_MODEL=claude-sonnet-4-5

# K8s Watcher (opcional)
CHATCLI_WATCH_DEPLOYMENT=myapp
CHATCLI_WATCH_NAMESPACE=production
CHATCLI_WATCH_INTERVAL=30s
CHATCLI_WATCH_WINDOW=2h
CHATCLI_WATCH_MAX_LOG_LINES=100

Próximo Passo