IronShell
EntrarComece agora

FAQ

Perguntas profundas sobre arquitetura, compliance, SLA enterprise, migração, bypass disclosure e roadmap.

Arquitetura e diferenciação

Como o IronShell se diferencia de frameworks que mudam toda semana?

O IronShell não compete com frameworks populares em amplitude de integrações. Ele escolheu profundidade de segurança, determinismo e cobertura de testes. A cada release major, os números acima (4.307 testes, 97,98% coverage, 132 padrões, 0 erros TypeScript) não podem regredir. Features que não atendem esses gates não entram.

Frameworks que publicam features semanalmente frequentemente têm dívida técnica acumulada invisível. O IronShell publica dentro do mesmo ritmo, mas cada release passa por:

  • Monte Carlo de 100 mil execuções adversariais.
  • Review de 7 conselheiros epistemicamente divergentes em decisões arquiteturais.
  • Code review por agente especialista dedicado.
  • Gate de performance (regressão > 15% barra o merge).
  • Security review específica.

Por que TypeScript e não Python?

Três razões.

Primeiro, agentes que escrevem código precisam de tipos. Python tem MyPy, mas o ecossistema de agentes em Python raramente usa type checking estrito. TypeScript em modo strict com zero erros não é opcional no IronShell — é enforced em CI.

Segundo, Node.js tem latência e throughput sensivelmente melhores para operações I/O e HTTP do que Python asyncio. Os benchmarks acima (REST dispatch em 2,6 milhões de ops/s) seriam impossíveis em CPython por conta do GIL.

Terceiro, V8 sandbox para JIT de código. O isolamento do V8 é mais maduro e testado do que qualquer equivalente em Python, e permite executar código arbitrário com garantias fortes de isolamento.

Open source vs enterprise: como funciona a migração?

O IronShell tem duas linhas de produto.

Open source (MIT) — o núcleo do framework, incluindo kernel NanoShield, memória, squad, JIT, self-healing, channels e a API REST completa. Licença MIT, código no GitHub, sem restrição de uso comercial.

Enterprise (comercial) — ativação de licença offline, SLA contratual, suporte via Slack dedicado, compliance SOC2, integração com IdP corporativo (SAML, OIDC), audit log retention estendida, kill-switch centralizado para frota de agentes, dashboards de governança multi-tenant.

Migração é aditiva: toda feature enterprise é ativada por flag. O código open source continua rodando no mesmo binário, sem fork. Você pode começar pagando zero, validar o sistema em produção, e ativar features enterprise quando faz sentido econômico.

Compliance

O IronShell é SOC2 compliant?

O IronShell fornece controles técnicos que compõem evidências SOC2 em diversas categorias TSC (Trust Services Criteria). A certificação SOC2 é do seu ambiente de operação, não do software.

Controles entregues pelo IronShell que ajudam na auditoria:

  • CC6.1 (Logical Access) — audit log encadeado HMAC, autenticação via IdP, rate limiting, kill-switch.
  • CC6.6 (Change Management) — versionamento semântico, assinatura digital de releases, rollout controlado.
  • CC7.2 (Monitoring) — OpenTelemetry traces, métricas Prometheus, alertas.
  • CC7.3 (Incident Response) — export de audit trail para análise forense, kill-switch remoto.
  • CC8.1 (Change Management) — verificação automática de integridade em cada deploy.

Contratos enterprise incluem um letter of support que detalha os controles disponíveis. Auditores externos validam o scope real da sua implantação.

LGPD e GDPR

O IronShell foi projetado com privacidade como primeiro requisito.

  • Zero dado de usuário sai da máquina por padrão — nenhuma telemetria automática.
  • Modo air-gapped totalmente suportado — ver cenário 4 em Deployment.
  • Data residency 100% local — todos os dados ficam no host onde o IronShell roda.
  • Right to be forgotten — comando CLI dedicado remove episódios associados a um identificador de usuário.
  • Data minimization — o IronShell não loga prompts ou responses completos por padrão; apenas metadata estruturada.
  • PII redaction — IronLeakDetector redige automaticamente credenciais, CPF, e padrões de dados pessoais quando configurado.

Para DPO (Data Protection Officer) enterprise, fornecemos DPA (Data Processing Agreement) padrão e suporte em RoPA (Records of Processing Activities).

HIPAA / PHI

O IronShell por si só não torna uma aplicação HIPAA-compliant. Ele não introduz novos requisitos de PHI handling quando implantado em infra já compatível. Para uso com dados de saúde:

  • Deploy em ambiente HIPAA-compliant (AWS HIPAA-eligible services, Azure HIPAA, etc.).
  • Habilite encryption at-rest em todos os volumes.
  • Configure audit log para retenção mínima de 6 anos.
  • Use provedor LLM com BAA (Business Associate Agreement): Azure OpenAI, Anthropic Enterprise, Google Workspace com BAA.
  • Nunca use provedores sem BAA (OpenAI API público, DeepSeek público, Groq público) para dados PHI.

ISO 27001

Os 102 padrões DENY do NanoShield fornecem evidência de controle técnico na categoria A.8.24 (Input/Output Validation) da ISO 27001:2022. Audit log e kill-switch cobrem A.8.15 (Logging) e A.8.5 (Secure Authentication).

Enterprise e SLA

Existe SLA enterprise?

Sim. Contratos enterprise incluem SLA contratual com os seguintes tiers:

  • Standard: 99,5% uptime para componentes não-LLM (kernel, memória, API), resposta em 4h em incidente P1 em horário comercial.
  • Business: 99,9% uptime, resposta em 1h em P1, 24/7.
  • Mission-critical: 99,99% uptime, resposta em 15min em P1, 24/7, engenheiro dedicado.

Note que uptime de LLM depende do provedor; o IronShell mitiga via SmartRouter e failover, mas não é contratualmente responsável pela disponibilidade dos provedores externos.

On-premise deployment é suportado?

Sim. Ver cenário 4 em Deployment. Suporte completo para:

  • Deploy air-gapped (zero saída para internet).
  • Ativação de licença offline (token único, renovável).
  • Provedor LLM local (Ollama, vLLM, modelo interno).
  • Backup local encriptado sem cloud.
  • Integração com IdP on-premise (Keycloak, ADFS).

Clientes em setor regulado (financeiro, saúde, governo) frequentemente preferem on-premise. O IronShell foi testado em instalações com esse perfil.

Multi-tenant governance

Em deployments enterprise, um painel central permite:

  • Criar tenants isolados (cada um com licença, budget e política NanoShield própria).
  • Provisionar usuários via SCIM sync.
  • Aplicar políticas de NanoShield diferenciadas por tenant.
  • Monitorar gastos de LLM por tenant com alertas.
  • Kill-switch por tenant em caso de incidente.

SSO via SAML / OIDC

Integração com provedores de identidade corporativos padrão:

  • Azure AD / Entra ID.
  • Okta.
  • Google Workspace.
  • Keycloak.
  • OneLogin.
  • Qualquer IdP SAML 2.0 ou OIDC 1.0 compliant.

JIT provisioning: usuários são criados automaticamente no primeiro login bem-sucedido via SSO.

Role-based access control

RBAC com 4 níveis padrão:

  • owner — controle total, incluindo billing, tenants, kill-switch global.
  • admin — configuração do tenant, gestão de usuários, políticas.
  • operator — uso do agente, invocação de skills, leitura de logs próprios.
  • viewer — apenas leitura (dashboards, métricas, status).

Permissões granulares por skill, tool ou endpoint são configuráveis. Operações sensíveis (disable NanoShield temporário, rotação de licença) requerem MFA além de role apropriada.

Audit log retention

Retenção padrão: 365 dias localmente + export para SIEM externo.

Retenção customizada (até 10 anos para compliance financeiro) via configuração. O audit log encadeado por HMAC permite verificação de integridade retroativa — se alguém alterar uma linha 2 anos depois, a verificação detecta.

Integração com vendors

E se Anthropic mudar a API do Claude?

O IronShell é um runtime separado que orquestra o Claude Code como engine oficial de inferência. Quando a Anthropic publica uma nova versão do Claude Code, três cenários possíveis:

  1. Mudança compatível (maioria dos casos) — a bateria automatizada de testes de compatibilidade confirma e a versão do runtime IronShell é certificada como compatível imediatamente.
  2. Mudança que afeta o runtime (raro) — o time do IronShell publica nova versão dentro do SLA enterprise contratual.
  3. Deprecação completa de API (não aconteceu) — existiria plano de migração documentado com suporte estendido para versão antiga.

A comunidade é notificada via GitHub Releases e email para licenciados enterprise. Em todos os releases do Claude Code oficial testados até hoje, a compatibilidade foi certificada dentro do SLA contratual.

Por que não usar só o Claude Code puro?

O Claude Code puro é excelente em desenvolvimento individual local. Ele não tem:

  • Auditoria obrigatória de tool calls via kernel de segurança.
  • Audit log encadeado HMAC.
  • Memória persistente entre sessões (cross-session KV).
  • SmartRouter entre 14 provedores LLM.
  • Squad multi-agente com consenso Byzantine.
  • JIT sandbox V8 para código novo.
  • RPA/desktop automation integrada.
  • Channels (Telegram, Slack, Discord) nativos.
  • Compliance (SOC2, LGPD, air-gapped).

Se você opera em produção, com dados sensíveis ou compliance, essas capacidades não são opcionais. O Claude Code é a fundação excelente; o IronShell adiciona o que falta para enterprise.

Custom NanoShield patterns para o nosso domínio

Sim, o corpus de padrões é extensível. Três formas de adicionar padrões customizados.

  1. Via config — adicionar padrões em ~/.ironshell/patterns.json local.
  2. Via painel — clientes enterprise podem publicar padrões para todos os seus tenants via painel.
  3. Via PR — padrões de interesse geral são aceitos no repositório upstream.

Padrões customizados passam pelas mesmas validações: Monte Carlo de 100k, false positive rate check, security review.

Operação prática

O IronShell funciona offline?

Sim, dentro de restrições.

  • Modo totalmente offline — requer provedor LLM local (Ollama, vLLM, LocalAI). Licença em modo offline ativado (token de 90 dias). Zero dependência de rede externa.
  • Modo parcialmente offline — cache de licença válido por 30 dias após última validação. Durante esse período, pode operar sem servidor de licença. LLM ainda exige conexão com o provedor escolhido.
  • Modo online padrão — validação de licença na inicialização, depois opera com cache. Rate limit e kill-switch requerem conexão ocasional.

Como faço backup?

Ver seção de backup em Deployment. Resumo: diretório ~/.ironshell/ contém toda a state persistente. Backup diário encriptado com age ou gpg para storage off-site. Restauração é trivial — copie o diretório e a sessão continua.

Data residency

100% local por padrão. Nenhum dado de episódio, audit log, memória ou configuração sai do host onde o IronShell roda.

Exceções:

  • Chamadas ao provedor LLM enviam prompts para o provedor escolhido. Para evitar, use provedor local (Ollama, vLLM).
  • Ativação de licença online envia identificador de máquina (hash) para o servidor do IronShell. Modo air-gapped evita totalmente.
  • Imunidade coletiva P2P, se habilitada, troca assinaturas de ataques com peers. Desabilitado em modo isolado.

O que acontece se a licença expirar?

Cache local de 30 dias entra em ação — o IronShell continua funcionando normalmente durante esse período. Após 30 dias sem validação, o cliente entra em modo degradado:

  • NanoShield continua ativo (segurança nunca é desabilitada).
  • Agent chat funciona, mas sem features enterprise (multi-tenant, SSO).
  • Aviso visível no terminal e dashboard.

Renovação de licença reativa imediatamente.

Breach notification policy

Se detectarmos comprometimento de alguma infra relevante (certificado, chave de assinatura, infra de publicação de releases), seguimos processo de 4 passos.

  1. Disclosure inicial em até 24h via email para licenciados e post em blog público.
  2. Análise técnica detalhada publicada em até 7 dias.
  3. Mitigação publicada com nova versão do software quando aplicável.
  4. Post-mortem completo em até 30 dias, incluindo timeline, root cause, ações de prevenção.

Licenças afetadas podem ser revogadas e reemitidas sem custo.

Bypass disclosure e bounty

Se eu encontrar um bypass no NanoShield?

Abra o disclosure de forma responsável.

  • E-mail: security@ironshell.cc
  • Chave PGP: disponível em /pgp-key.asc do site.
  • Prazo: respondemos em até 48h, triage completa em até 7 dias.

Não abra issue pública antes da resolução. Não tente o bypass em infra de terceiros sem autorização.

Programa de bounty

Pagamento por bypass validado, escalonado por severidade:

  • Low (edge case, requer contexto específico): $100-500.
  • Medium (bypass em classe de ataque documentada): $500-2.000.
  • High (bypass em múltiplas classes, generalizável): $2.000-5.000.
  • Critical (bypass universal de uma categoria inteira): $5.000-15.000.

Pagamento em USD via transferência ou equivalente em crypto. Reconhecimento público em hall of fame (opcional).

Roadmap e futuro

Próximos releases

  • v9.5 — IronForge (GitHub issue → PR autônomo via ADE pipeline). Shield Evolution (aprendizado de padrões em produção). GGUF export para modelos locais.
  • v9.6 — IronVision Analytics (observabilidade multimodal). Web dashboard v2 (React 19).
  • v10.0 — Rust NAPI-rs rewrite dos hot paths (NanoShield, parse, memória BM25). Target: 3-5x throughput sem breaking changes de API.

Podemos influenciar o roadmap?

Sim. Duas vias:

  • Issues públicas — contribuições bem escritas, com contexto e exemplos, têm altíssima chance de entrar.
  • Enterprise — contratos enterprise incluem sessão mensal de roadmap feedback com o time core.

A Anthropic é parceira oficial?

O IronShell não tem afiliação oficial com a Anthropic. O sistema é um runtime enterprise construído como camada autônoma que orquestra o Claude Code (open source Anthropic) como engine oficial de inferência. Relação técnica, não comercial.

Perguntas comuns de devs

Suporta Windows?

Sim. Windows 10 22H2+ e Windows 11. Instalação via PowerShell ou comando de 1 linha (irm ironshell.cc/install | iex). Node.js é baixado automaticamente se não estiver presente.

Suporta Bun / Deno?

Node.js 20.10+ é o runtime suportado oficialmente. Bun funciona em modo experimental (algumas features de vm podem diferir). Deno não é suportado no momento — incompatibilidade com algumas dependências nativas.

Como rodar em container com Node.js 22?

FROM node:22-bookworm-slim
RUN apt-get update && apt-get install -y python3 curl ca-certificates
WORKDIR /app
RUN npm install -g ironshell@latest
ENV IRONSHELL_PROVIDER=smart-router
ENTRYPOINT ["ironshell"]
CMD ["--serve", "--port", "3000"]

Posso forkar?

Sim, MIT. Faça fork com atribuição, envie PRs de volta quando fizer sentido, e se construir algo comercial em cima, considere uma doação para o projeto upstream.

Como reportar bug reprodutível?

Abra issue no GitHub com:

  1. Versão do IronShell (ironshell --version).
  2. Versão do Node.js (node --version).
  3. Sistema operacional e versão.
  4. Comando que reproduz o bug.
  5. Output esperado vs output observado.
  6. Log relevante (~/.ironshell/audit.log dos últimos 5 minutos, sanitizado).

Claude Code ou ChatGPT Desktop? Qual?

Escolhas com propósitos diferentes. Claude Code é um agente de código de linha de comando, integrado com git, com MCP e com o ecossistema dev. ChatGPT Desktop é um cliente de chat com voz. O IronShell estende o Claude Code; não tem integração específica com ChatGPT Desktop.

Tem client móvel (iOS / Android)?

Não oficialmente. O IronShell expõe API REST; qualquer cliente móvel que fale HTTP consegue integrar. Comunidade mantém um cliente Android não oficial em github.com/ironshell/android-client.

Licenciamento

Qual licença o core usa?

MIT. Sem restrição de uso comercial, sem obrigação de publicar modificações.

Posso incluir IronShell em produto SaaS comercial que eu vendo?

Sim. MIT permite. Se o IronShell é peça central do produto, considere uma parceria para suporte dedicado.

Tenho garantias contratuais?

No open source, não. MIT vem sem garantias. Contratos enterprise incluem SLA, suporte, limitações de responsabilidade, e indenização por IP.

Próximos passos

  • Voltar para Overview se acabou de chegar.
  • Ler Segurança para entender a profundidade do kernel.
  • Ler Deployment para cenários de produção.
  • Para contato enterprise: enterprise@ironshell.cc.
  • Para contato de segurança: security@ironshell.cc.