IronShell
EntrarComece agora

Deployment e self-host

Cenários de deploy: local, VPS, cloud, enterprise on-premise, air-gapped. Backup, HA, monitoring.

Visão geral dos cenários

O IronShell foi desenhado para rodar em praticamente qualquer ambiente onde Node.js 20 execute. Esta página cobre os quatro cenários canônicos de deploy, do mais simples ao mais restrito, com requisitos, procedimentos e recomendações.

  1. Local — laptop do desenvolvedor, uso individual.
  2. VPS — servidor compartilhado ou dedicado em cloud pública.
  3. Cloud privada — AWS, GCP, Azure com deploy próprio.
  4. On-premise / air-gapped — infra corporativa isolada.

Para cada cenário, listamos hardware mínimo recomendado, segurança por camada, estratégia de backup e observações operacionais.

Cenário 1 — Deploy local

Hardware mínimo

  • Laptop ou desktop com Node.js 20.10+.
  • 8 GB de RAM (2 GB para o IronShell, resto para navegador, IDE, etc.).
  • 10 GB de espaço livre em SSD.

Instalação

Descrito em detalhes em Começando. Resumo: curl -fsSL https://ironshell.cc/install.sh | bash em macOS/Linux; iwr -useb https://ironshell.cc/install.ps1 | iex em Windows.

Dados persistidos

  • ~/.ironshell/config.json — configuração global.
  • ~/.ironshell/license.enc — licença com cache HMAC de 30 dias.
  • ~/.ironshell/episodes.db — SQLite WASM com memória episódica.
  • ~/.ironshell/knowledge.db — Knowledge Graph.
  • ~/.ironshell/audit.log — audit chain HMAC.
  • ~/.ironshell/skills/ — skills instaladas localmente.

Backup

Um script diário que copia ~/.ironshell/ para um destino seguro é suficiente. Exemplo:

#!/bin/bash
DEST="$HOME/Backups/ironshell/$(date +%Y-%m-%d)"
mkdir -p "$DEST"
cp -a ~/.ironshell/ "$DEST/"
find "$HOME/Backups/ironshell" -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \;

Encripte com gpg ou age antes de subir para cloud se a memória contém dados sensíveis.

Cenário 2 — VPS

Deploy em servidor único em provedores como Hetzner, Contabo, DigitalOcean, Linode, Vultr.

Hardware mínimo recomendado

| Recurso | Mínimo | Recomendado | Uso intensivo | | --- | --- | --- | --- | | CPU | 2 vCPU | 4 vCPU | 8 vCPU | | RAM | 4 GB | 8 GB | 16 GB | | Disco | 40 GB SSD | 100 GB NVMe | 500 GB NVMe | | Rede | 100 Mbps | 1 Gbps | 10 Gbps |

Provedores recomendados

  • Hetzner Cloud — melhor custo-benefício. Servidor CX21 (2 vCPU, 4 GB RAM, 40 GB) por aproximadamente 5-6 EUR/mês.
  • Contabo VPS — memória abundante por preço baixo. VPS S (4 vCPU, 8 GB, 50 GB NVMe) a ~7 EUR/mês.
  • DigitalOcean — UI simples, marketplace de imagens, boa para quem prioriza DX.
  • OVH — data centers em múltiplas regiões, forte em Europa.

Deploy via Docker

# docker-compose.yml
services:
  ironshell:
    image: ghcr.io/ironshell/ironshell:latest
    ports:
      - "3000:3000"
    environment:
      IRONSHELL_LICENSE_FILE: /run/secrets/ironshell_license
      IRONSHELL_PROVIDER: smart-router
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY}
    secrets:
      - ironshell_license
    volumes:
      - ironshell_data:/home/ironshell/.ironshell
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/v1/health"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  ironshell_data:

secrets:
  ironshell_license:
    file: ./license.key

TLS com Caddy

# Caddyfile
ironshell.seu-dominio.com {
  reverse_proxy localhost:3000
  tls admin@seu-dominio.com
  log {
    output file /var/log/caddy/ironshell.log
  }
}

Caddy cuida automaticamente do certificado Let's Encrypt via ACME. Zero configuração adicional.

Firewall

# UFW
ufw default deny incoming
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Deixe a porta 3000 fechada para internet — acesso apenas via Caddy na 443.

Backup automatizado

# /etc/cron.daily/ironshell-backup
#!/bin/bash
set -e
BACKUP_DIR="/backup/ironshell/$(date +%Y-%m-%d)"
mkdir -p "$BACKUP_DIR"

# Stop para backup consistente do SQLite
docker compose -f /opt/ironshell/docker-compose.yml stop
docker run --rm -v ironshell_data:/data -v "$BACKUP_DIR":/backup alpine tar czf /backup/data.tar.gz -C /data .
docker compose -f /opt/ironshell/docker-compose.yml start

# Encriptar
age -r age1... "$BACKUP_DIR/data.tar.gz" > "$BACKUP_DIR/data.tar.gz.age"
rm "$BACKUP_DIR/data.tar.gz"

# Upload para S3-compatible (Backblaze B2, Wasabi, R2)
aws s3 cp "$BACKUP_DIR/" "s3://backup-bucket/ironshell/" --recursive --endpoint-url https://s3.us-west-002.backblazeb2.com

# Remove backups locais > 7 dias
find /backup/ironshell -maxdepth 1 -type d -mtime +7 -exec rm -rf {} \;

Cenário 3 — Cloud privada

Para deploys em AWS, GCP ou Azure com requisitos de HA, observability e compliance.

AWS

Arquitetura recomendada

Route 53 (DNS)
    |
    v
CloudFront (CDN, WAF, DDoS)
    |
    v
ALB (Application Load Balancer)
    |
    v
ECS Fargate (2-4 tasks IronShell)
    |
    +-- EFS (shared storage para episodes.db, audit.log)
    |
    +-- RDS Postgres (opcional: memória externa)
    |
    +-- Secrets Manager (licenças, API keys)
    |
    +-- CloudWatch Logs + X-Ray (observability)

Por que ECS Fargate

  • Sem servidor para administrar.
  • Auto-scaling baseado em CPU/memória.
  • Rotação automática de tasks (rolling deploy).
  • Health checks via ALB.

IAM mínimo

  • secretsmanager:GetSecretValue para licenças e API keys.
  • s3:GetObject / s3:PutObject para backups.
  • logs:CreateLogStream / logs:PutLogEvents.
  • Não é necessário IAM para LLM — a autenticação é via API keys lidas do Secrets Manager.

GCP

Equivalente via Cloud Run + Cloud SQL + Secret Manager. Cloud Run escala a zero se não há tráfego, o que reduz custo.

Azure

Container Apps + Azure SQL + Key Vault. Se você já usa Azure OpenAI, essa é a combinação mais alinhada — data residency garantida dentro da região.

Kubernetes + Helm

Para quem opera K8s, existe chart Helm básico:

helm repo add ironshell https://charts.ironshell.cc
helm install ironshell ironshell/ironshell \
  --set replicas=3 \
  --set license.secretName=ironshell-license \
  --set providers.anthropic.secretName=anthropic-key \
  --set persistence.storageClass=gp3 \
  --set persistence.size=100Gi

O chart configura:

  • Deployment com readiness/liveness probes.
  • Service + Ingress com cert-manager.
  • PVC para dados persistentes.
  • HPA baseado em CPU/memória.
  • PDB para resiliência em node drain.

High availability

Para operação 24/7 com tolerância a falha de um nó:

  • 3 réplicas mínimo, distribuídas em 3 AZs.
  • PostgreSQL externo para memória — com replicação master-replica.
  • Redis para session state (opcional, se quiser sessão sticky).
  • Load balancer com health checks de 30 segundos.
  • PodDisruptionBudget permite no máximo 1 pod offline simultaneamente.

Cenário 4 — On-premise e air-gapped

Ambientes corporativos com zero saída de dados para internet.

Requisitos

  • Cluster Kubernetes on-premise (K3s, Rancher, OpenShift) ou VMs em VMware/Proxmox.
  • Registry interno para imagens (Harbor, JFrog, Nexus).
  • Provedor LLM local (Ollama, vLLM, LocalAI ou modelo em infra privada).
  • Storage persistente (NFS, Ceph, Longhorn, Portworx).

Deploy sem internet

  1. Baixar IronShell image em rede com acesso, via docker pull ghcr.io/ironshell/ironshell:v9.4.0.
  2. Exportar com docker save -o ironshell-v9.4.0.tar ghcr.io/ironshell/ironshell:v9.4.0.
  3. Transportar (USB sanitizado ou air-gap file transfer oficial).
  4. Importar na rede isolada com docker load -i ironshell-v9.4.0.tar.
  5. Push para registry interno.
  6. Deploy apontando para o registry interno.

Licença em modo air-gapped

Licenças enterprise permitem ativação offline com token único. O processo:

  1. Gera request.bin no host air-gapped com ironshell license offline-request.
  2. Transporta para host com internet.
  3. Envia para endpoint de ativação offline no painel.
  4. Recebe activation.bin.
  5. Transporta de volta e ativa com ironshell license offline-activate activation.bin.

Validade típica: 90 dias por ativação. Reativação segue o mesmo fluxo.

Provedor LLM local

# Ollama em servidor GPU dedicado
docker run -d --gpus all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
docker exec ollama ollama pull llama3.3:70b

# IronShell aponta para Ollama interno
IRONSHELL_PROVIDER=ollama
OLLAMA_HOST=http://ollama-server.internal:11434
OLLAMA_MODEL=llama3.3:70b

Para carga pesada, use vLLM em GPU dedicada (H100 ou A100):

docker run -d --gpus all -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.3-70B-Instruct

Segurança por camada

Network

  • Firewall permite apenas portas explicitamente usadas (443, 3000 no localhost).
  • VPN obrigatória para acesso administrativo.
  • Rede privada separada para tráfego LLM interno (se usar Ollama/vLLM).
  • P2P imunidade coletiva desabilitada em ambientes air-gapped (config: IRONSHELL_IMMUNITY_P2P=false).

Storage

  • Criptografia at-rest em todos os volumes persistentes (LUKS, dm-crypt, ou equivalente).
  • Backup criptografado antes de sair do host.
  • Chaves mestras em HSM ou KMS, não em arquivos texto.

Auth

  • Integração com IdP corporativo via SAML ou OIDC (Azure AD, Okta, Keycloak).
  • MFA obrigatório para acesso ao painel administrativo.
  • Rotação automática de tokens de API a cada 90 dias.

Audit

  • Audit log encadeado por HMAC-SHA256.
  • Export diário para sistema SIEM (Splunk, Elastic, Chronicle).
  • Retenção configurável (padrão: 365 dias).
  • Integridade verificável com comando CLI dedicado.

Monitoring

Métricas

Endpoint /v1/metrics expõe formato Prometheus:

# HELP ironshell_requests_total Total de requests por endpoint e status
# TYPE ironshell_requests_total counter
ironshell_requests_total{endpoint="/v1/chat",status="200"} 128456
ironshell_requests_total{endpoint="/v1/chat",status="403"} 12

# HELP ironshell_nanoshield_risk_score_bucket Distribuição de risk scores
# TYPE ironshell_nanoshield_risk_score_bucket histogram
ironshell_nanoshield_risk_score_bucket{le="10"} 94523
ironshell_nanoshield_risk_score_bucket{le="40"} 2148
ironshell_nanoshield_risk_score_bucket{le="70"} 44
ironshell_nanoshield_risk_score_bucket{le="+Inf"} 3

# HELP ironshell_llm_cost_usd_total Custo acumulado por provider
# TYPE ironshell_llm_cost_usd_total counter
ironshell_llm_cost_usd_total{provider="anthropic"} 12.45
ironshell_llm_cost_usd_total{provider="deepseek"} 0.12

Tracing

OpenTelemetry para Jaeger ou Tempo. Veja exemplo em Integrações.

Alerting

Exemplos de regras Prometheus/Alertmanager:

groups:
  - name: ironshell
    rules:
      - alert: HighRiskScoreRate
        expr: rate(ironshell_nanoshield_blocked_total[5m]) > 0.1
        for: 10m
        annotations:
          summary: "IronShell bloqueando >10% das requests em 10 minutos"

      - alert: LLMBudgetNearCap
        expr: ironshell_llm_cost_usd_total / ironshell_llm_budget_cap > 0.9
        annotations:
          summary: "Budget LLM do provider {{ $labels.provider }} em 90%"

      - alert: LicenseExpiringSoon
        expr: ironshell_license_expires_seconds < 7 * 24 * 3600
        annotations:
          summary: "Licença IronShell expira em <7 dias"

Hardening de segurança

Checklist antes de colocar em produção.

  • [ ] TLS obrigatório em todas as rotas externas.
  • [ ] Rate limit configurado para /v1/chat (sugestão: 60 req/min por token).
  • [ ] Audit log exportado para SIEM externo a cada hora.
  • [ ] Backup encriptado diário em localização off-site.
  • [ ] Licença em HSM ou KMS, não em .env texto.
  • [ ] Logs não contêm PII em claro (o IronLeakDetector filtra automaticamente).
  • [ ] Health checks do orquestrador monitorando /v1/health.
  • [ ] Alert configurado para bloqueios em excesso (possível incident de segurança).
  • [ ] MFA para acesso ao painel admin.
  • [ ] Rotação programada de API keys dos LLM (90 dias).
  • [ ] Revisão trimestral dos padrões NanoShield ativos.

Requisitos para compliance SOC2

O IronShell não substitui um programa SOC2, mas fornece os controles técnicos que compõem evidências nas seguintes categorias TSC (Trust Services Criteria):

  • CC6.1 (Logical Access) — audit log encadeado, auth via IdP.
  • CC6.6 (Change Management) — versionamento semântico de releases, rollout controlado.
  • CC7.2 (Monitoring) — OTEL traces, Prometheus metrics, alertas.
  • CC7.3 (Incident Response) — kill-switch, audit export para análise forense.
  • CC8.1 (Change Management) — assinatura digital de alterações de software, verificação automática.

Para auditoria formal, consulte a FAQ e o contato enterprise.

Atualização de versão

Releases seguem semver. Minor versions são backward-compatible; major versions podem ter breaking changes documentadas.

# Verificar versão atual
ironshell --version

# Checar se há update
ironshell self-update --check

# Aplicar update (não destrutivo, mantém dados)
ironshell self-update

Em Docker/K8s, basta atualizar a tag da imagem e fazer rolling deploy. O IronShell migra automaticamente o schema local se necessário, mantendo backup do schema anterior por 30 dias.

Próximos passos

  • Benchmarks — performance medida dos componentes críticos.
  • FAQ — compliance, SLA, enterprise licensing.
  • Segurança — detalhes do kernel e benchmarks acadêmicos.