Modo Servidor (chatcli server)

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

Modo mais simples

Servidor na porta padrão (50051):

chatcli server

Com porta e autenticação customizados

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

Com TLS habilitado

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

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

Com fallback de provedores (opcional)

chatcli server --fallback-providers OPENAI,CLAUDEAI,GOOGLEAI,OPENROUTER,ZAI,MINIMAX,MOONSHOT,COPILOT

Com MCP (opcional)

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

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 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 Var	Descrição	Padrão
`CHATCLI_GRPC_REFLECTION`	Habilita gRPC reflection para debugging. Requer AMBOS a flag `--grpc-reflection` E esta variável como `true`. Mantenha desabilitado em produção. Configurável via Helm com `server.grpcReflection`.	`false`
`CHATCLI_DISABLE_VERSION_CHECK`	Desabilita verificação automática de versão no startup.	`false`
`CHATCLI_BIND_ADDRESS`	Endereço de bind do servidor. Padrão `127.0.0.1` (local); em Kubernetes, auto-detecta via `KUBERNETES_SERVICE_HOST` e usa `0.0.0.0`. Valor explícito sempre prevalece.	`127.0.0.1` / `0.0.0.0` (K8s)

O gRPC reflection agora requer duas condições: a flag --grpc-reflection E a variável CHATCLI_GRPC_REFLECTION=true. Isso evita habilitação acidental em produção. Veja a documentação de segurança para todas as medidas de hardening.

O endereço de bind padrão é 127.0.0.1 (seguro para uso local). Em Kubernetes, o servidor auto-detecta o ambiente via KUBERNETES_SERVICE_HOST e automaticamente usa 0.0.0.0 — nenhuma configuração adicional é necessária. Um valor explícito em CHATCLI_BIND_ADDRESS sempre prevalece.

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
JWT com RBAC
TLS (HTTPS)

Por padrão, o servidor não exige autenticação. Qualquer cliente pode conectar:

chatcli server  # sem --token = acesso livre

Defina um token para proteger o servidor:

# Via flag
chatcli server --token meu-token-secreto

# Via variável de ambiente
export CHATCLI_SERVER_TOKEN=meu-token-secreto
chatcli server

O cliente precisa fornecer o mesmo token ao conectar:

chatcli connect servidor:50051 --token meu-token-secreto

Para controle de acesso baseado em roles, configure autenticação JWT:

export CHATCLI_JWT_SECRET="minha-chave-secreta-256-bits"
export CHATCLI_JWT_ISSUER="chatcli-server"
export CHATCLI_JWT_AUDIENCE="chatcli-api"
chatcli server

O servidor valida tokens JWT e extrai a role do claim role. Três roles estão disponíveis:

Role	Permissões
`admin`	Acesso total: gerenciar sessões, executar plugins, configurar servidor
`user`	Executar plugins, gerenciar suas próprias sessões, enviar prompts
`readonly`	Apenas visualizar: listar sessões, consultar status do servidor

Exemplo: gerando um JWT para um usuário:

import "github.com/golang-jwt/jwt/v5"

claims := jwt.MapClaims{
    "sub":  "usuário@empresa.com",
    "role": "user",
    "iss":  "chatcli-server",
    "aud":  "chatcli-api",
    "exp":  time.Now().Add(24 * time.Hour).Unix(),
}
token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
signed, _ := token.SignedString([]byte(os.Getenv("CHATCLI_JWT_SECRET")))

O rate limiting de autenticação bloqueia IPs após 5 falhas por minuto. Isso protege contra ataques de força bruta em tokens e JWTs.

Para conexões encriptadas, forneça certificado e chave TLS. O servidor exige TLS 1.3 como versão mínima:

chatcli server --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

O cliente usa a flag --tls e opcionalmente --ca-cert:

chatcli connect servidor:50051 --tls --ca-cert /path/to/ca.pem

mTLS (Mutual TLS): Para autenticação mútua, configure também o certificado do cliente:

export CHATCLI_TLS_CLIENT_CERT=/path/to/client-cert.pem
export CHATCLI_TLS_CLIENT_KEY=/path/to/client-key.pem
chatcli server --tls-cert cert.pem --tls-key key.pem

Se o carregamento do certificado TLS falhar, o erro é escrito tanto em stderr quanto no log estruturado, incluindo os caminhos do certificado e da chave para facilitar o diagnóstico. Em Kubernetes, verifique com kubectl logs para visualizar o erro.

Modos de Credencial

O servidor suporta múltiplos modos de credencial LLM, dando flexibilidade total:

1. Credenciais do Servidor (Padrão)

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.

2. Credenciais do Cliente (API Key)

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

3. Credenciais do Cliente (OAuth Local)

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

4. Credenciais StackSpot

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>

5. GitHub Copilot (OAuth Local)

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

6. Ollama (Sem Credenciais)

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:

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 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;
}

REST API Gateway

Além do gRPC, o operator agora expõe uma API REST HTTP na porta :8090 com:

30+ endpoints cobrindo incidents, SLOs, runbooks, approvals, postmortems, analytics, clusters e audit
Autenticação via X-API-Key com mapeamento de roles (viewer/operator/admin)
Rate limiting de 100 req/min por chave
Web Dashboard embutido servido em /

Para referência completa, consulte a API Reference.

Comandos Remotos via InteractiveSession

Ao conectar a um servidor via chatcli connect, a sessão interativa suporta comandos executados diretamente no servidor:

Comando	Descrição
`/status`	Informações do servidor (versão, provider, modelo, uptime)
`/watcher status`	Detalhes do K8s Watcher (targets, snapshots, alertas)
`/plugins list`	Lista plugins disponíveis no servidor
`/agents list`	Lista agents disponíveis no servidor
`/skills list`	Lista skills disponíveis no servidor

Esses comandos são processados pelo servidor e retornam resultados via streaming gRPC bidirecional (InteractiveSession).

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)

chatcli server --watch-deployment myapp --watch-namespace production

chatcli server --watch-config targets.yaml

O arquivo targets.yaml define múltiplos deployments, métricas Prometheus e budget de contexto. Veja K8s Watcher para o formato completo.

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?
> Análise as métricas HTTP do api-gateway

Rate Limiting

O servidor implementa rate limiting por cliente usando token bucket para proteger contra abuso:

Variável	Descrição	Padrão
`CHATCLI_RATE_LIMIT_RPS`	Requisições por segundo por cliente	`10`
`CHATCLI_RATE_LIMIT_BURST`	Burst máximo permitido	`30`

Quando o limite é atingido, o servidor retorna o código gRPC ResourceExhausted com um header Retry-After indicando quantos segundos o cliente deve aguardar.

export CHATCLI_RATE_LIMIT_RPS=20
export CHATCLI_RATE_LIMIT_BURST=50
chatcli server

Em ambientes com múltiplos clientes legítimos, aumente o burst para acomodar picos de uso. O RPS controla a taxa sustentada.

Prevenção de SSRF

O servidor valida todas as URLs configuradas em provider_config antes de utilizá-las, bloqueando:

IPs privados: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
Metadados de cloud: 169.254.169.254 (AWS, GCP, Azure)
Link-local: 169.254.0.0/16, fe80::/10
Loopback: 127.0.0.0/8, ::1

Isso impede que provedores LLM maliciosos ou configurações incorretas acessem recursos internos da rede. A validação ocorre antes de qualquer requisição HTTP ser enviada.

Limites de Tamanho de Mensagem

Variável	Descrição	Padrão
`CHATCLI_MAX_RECV_MSG_SIZE`	Tamanho máximo de mensagem recebida	`50MB`
`CHATCLI_MAX_SEND_MSG_SIZE`	Tamanho máximo de mensagem enviada	`50MB`
`CHATCLI_MAX_CONCURRENT_STREAMS`	Streams simultâneas por conexão	`100`

Esses limites protegem contra ataques de esgotamento de recursos e garantem estabilidade do servidor sob carga.

Audit Logging

O servidor pode gerar logs de auditoria em formato JSON-lines para rastreabilidade completa:

Variável	Descrição	Padrão
`CHATCLI_AUDIT_LOG_PATH`	Caminho do arquivo de audit log (vazio = desabilitado)	`""`

Cada requisição recebe um Request ID único para correlação. Os eventos registrados incluem:

Autenticação (sucesso/falha)
Execução de prompts e plugins
Operações de sessão (save/load/delete)
Alterações de configuração

export CHATCLI_AUDIT_LOG_PATH=/var/log/chatcli/audit.jsonl
chatcli server

O formato JSON-lines facilita integração com ferramentas como jq, Elasticsearch, Loki e Splunk. Cada linha é um objeto JSON independente com timestamp, request ID, ação e resultado.

Rotação de Logs

Variável	Descrição	Padrão
`CHATCLI_LOG_FILE`	Caminho do arquivo de log principal	`""` (stdout)
`CHATCLI_LOG_MAX_SIZE_MB`	Tamanho máximo antes de rotacionar	`100`
`CHATCLI_LOG_MAX_BACKUPS`	Número de backups antigos a manter	`5`
`CHATCLI_LOG_MAX_AGE_DAYS`	Dias máximos de retenção	`30`
`CHATCLI_LOG_COMPRESS`	Comprimir backups com gzip	`true`

export CHATCLI_LOG_FILE=/var/log/chatcli/server.log
export CHATCLI_LOG_MAX_SIZE_MB=50
export CHATCLI_LOG_MAX_BACKUPS=10
chatcli server

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
CHATCLI_BIND_ADDRESS=127.0.0.1  # Auto-detectado como 0.0.0.0 em Kubernetes

# Segurança
CHATCLI_GRPC_REFLECTION=false
CHATCLI_DISABLE_VERSION_CHECK=false
CHATCLI_JWT_SECRET=minha-chave-secreta
CHATCLI_JWT_ISSUER=chatcli-server
CHATCLI_JWT_AUDIENCE=chatcli-api

# Rate Limiting
CHATCLI_RATE_LIMIT_RPS=10
CHATCLI_RATE_LIMIT_BURST=30

# Limites de Mensagem
CHATCLI_MAX_RECV_MSG_SIZE=52428800
CHATCLI_MAX_SEND_MSG_SIZE=52428800
CHATCLI_MAX_CONCURRENT_STREAMS=100

# mTLS
CHATCLI_TLS_CLIENT_CERT=/path/to/client-cert.pem
CHATCLI_TLS_CLIENT_KEY=/path/to/client-key.pem

# Auditoria e Logs
CHATCLI_AUDIT_LOG_PATH=/var/log/chatcli/audit.jsonl
CHATCLI_LOG_FILE=/var/log/chatcli/server.log
CHATCLI_LOG_MAX_SIZE_MB=100

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

# 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

Conexão Remota

Conectar ao servidor remotamente

K8s Watcher

Multi-target + Prometheus

K8s Operator

K8s Operator (AIOps)

Deploy

Deploy com Docker e Helm

​Por que usar o Modo Servidor?

Centralização

Segurança

Flexibilidade

Performance

​Iniciando o Servidor

​Flags Disponíveis

​Flags de Fallback (opcionais)

​Flag MCP (opcional)

​Prometheus Metrics

​Variáveis de Segurança

​Flags do K8s Watcher (opcionais)

​Autenticação do Servidor

​Modos de Credencial

​Arquitetura gRPC

​gRPC com Múltiplas Réplicas

​Streaming Progressivo

​RPCs de Descoberta de Recursos

​RPCs da Plataforma AIOps

​GetAlerts

​AnalyzeIssue

​REST API Gateway

​Comandos Remotos via InteractiveSession

​Integração com K8s Watcher

​Rate Limiting

​Prevenção de SSRF

​Limites de Tamanho de Mensagem

​Audit Logging

​Rotação de Logs

​Variáveis de Ambiente

​Próximo Passo

Conexão Remota

K8s Watcher

K8s Operator

Deploy

Por que usar o Modo Servidor?

Iniciando o Servidor

Flags Disponíveis

Flags de Fallback (opcionais)

Flag MCP (opcional)

Prometheus Metrics

Variáveis de Segurança

Flags do K8s Watcher (opcionais)

Autenticação do Servidor

Modos de Credencial

Arquitetura gRPC

gRPC com Múltiplas Réplicas

Streaming Progressivo

RPCs de Descoberta de Recursos

RPCs da Plataforma AIOps

GetAlerts

AnalyzeIssue

REST API Gateway

Comandos Remotos via InteractiveSession

Integração com K8s Watcher

Rate Limiting

Prevenção de SSRF

Limites de Tamanho de Mensagem

Audit Logging

Rotação de Logs

Variáveis de Ambiente

Próximo Passo