IronShell
EntrarComece agora

Começando com IronShell

Pré-requisitos, instalação em 30 segundos, ativação de licença e primeiros comandos.

Pré-requisitos

Antes de instalar, confirme que o ambiente atende o mínimo.

| Requisito | Valor mínimo | Recomendado | | --- | --- | --- | | Node.js | 20.10.0 | 22.x LTS | | RAM | 2 GB livres | 8 GB | | Espaço em disco | 400 MB | 2 GB | | SO | Windows 10, macOS 12, Linux com glibc 2.31 | Windows 11, macOS 14, Ubuntu 22.04 | | Conexão | Saída HTTPS para o provedor LLM | Saída para ativação + P2P opcional | | Arquitetura | x64 ou arm64 | arm64 em Apple Silicon |

O IronShell não requer GPU para operação normal. A GPU só entra em cena se você optar por rodar modelos locais via Ollama, vLLM ou LocalAI, ou se ativar o pipeline de fine-tuning IronML. Nesses casos, uma GTX 1060 ou superior é suficiente para começar.

Instalação em 30 segundos

O instalador guiado detecta o sistema operacional, escolhe o binário correto, valida a integridade via SHA-256 e deixa o ironshell disponível no PATH.

Windows (PowerShell)

iwr -useb https://ironshell.cc/install.ps1 | iex

macOS e Linux (Bash)

curl -fsSL https://ironshell.cc/install.sh | bash

Alternativa: npm

Se você já tem Node.js e prefere controlar o processo manualmente:

npm install -g ironshell

Ativação da licença

Na primeira execução, o ironshell detecta que não há licença ativa e abre um navegador com o link de ativação único para a máquina atual. Você cola a licença que recebeu no painel, e o cliente faz três coisas em sequência.

  1. Verifica a assinatura Ed25519 da licença contra a chave pública do servidor (embutida no binário e pinned via SHA-256 do certificado TLS).
  2. Faz o machine binding gerando um identificador POSIX-safe e estável da máquina — sem depender de MAC address, que é volátil e spoofável.
  3. Registra o pareamento no servidor via um challenge-response assinado. O servidor guarda apenas o hash do identificador, nunca o valor bruto.

A licença é válida por padrão em uma única máquina. Planos enterprise permitem múltiplos nós com um cap configurável. Se a máquina mudar de nome, disco ou placa-mãe, o IronShell detecta e pede reativação — isso é um feature, não um bug, e existe para impedir clonagem silenciosa.

Operação offline

Após a primeira ativação online, o cliente mantém um cache HMAC-SHA256 da licença válida por 30 dias. Durante esse período, o IronShell funciona sem contactar o servidor. Isso cobre viagens, ambientes air-gapped temporários e quedas de rede.

Kill-switch remoto

Licenças comprometidas (leak, fraude, chargeback) podem ser revogadas remotamente. O cliente detecta a revogação na próxima sincronização e se recusa a operar, mas nunca toca no código do Claude Code base — você pode continuar usando a CLI oficial sem interrupção.

Primeiro comando

Depois de ativar, abra um terminal em qualquer projeto e rode:

ironshell

O comando abre o REPL interativo. O prompt é idêntico ao do Claude Code, com um indicador de status que mostra o estado do NanoShield, o provedor ativo e o saldo de budget consumido na sessão.

Experimente alguns comandos para sentir o comportamento.

Comando inócuo

> list the 5 largest files in this folder

O agente chama a skill de listagem, o NanoShield atribui risk score baixo (tipicamente 5), e o comando executa. O resultado aparece em segundos.

Comando destrutivo

> delete all .log files in /var/log

O NanoShield identifica o pattern de destruição recursiva em diretório de sistema, atribui risk score alto e bloqueia. Você vê uma resposta estruturada explicando o motivo: qual pattern casou, qual era o risk score, qual diretório estava sob ameaça. Nada executa.

Comando com evasão Unicode

> ｒｍ -ｒｆ /

Os caracteres fullwidth parecem diferentes de ASCII para um regex ingênuo, mas o NanoShield aplica normalização NFKC antes da análise. O resultado é o mesmo do caso anterior: bloqueado com risk score 95, referência ao pattern destruição + normalização Unicode.

Primeira conversa (exemplo real)

Veja um ciclo completo típico:

> can you analyze the structure of src/ and suggest what to refactor first?

IRON  Running repo analyzer.
IRON  PageRank computed for 187 files, top 5 hotspots identified.
IRON  Cross-references mapped, 3 circular candidates flagged (all false positives).
IRON  Kernel risk score of all internal actions: avg 3 / max 8.

Summary:
1. The most connected module (rank 0.087) is the main agent loop.
   Consider extracting the turn-building logic into a dedicated submodule.
2. The security kernel file has grown to 2100 lines. Splitting per
   pattern category would improve maintainability without touching tests.
3. The community skills directory contains 53 independent scripts;
   no refactor needed there.

Next action suggestion: extract the turn builder into a dedicated module.
Estimated diff: ~180 lines, zero test regression.

Nessa execução o agente usou a skill de análise de repositório, gerou o resultado determinístico via PageRank, nunca tocou em arquivo e ainda sugeriu o próximo passo. Cada ação intermediária passou pelo kernel de segurança — o log completo está disponível em ~/.ironshell/audit.log, encadeado por HMAC.

Troubleshooting inicial

"Licença inválida" depois de colar a chave

Verifique se copiou a chave inteira, incluindo os grupos separados por hífen. O formato é IRSH-XXXX-XXXX-XXXX-XXXX-XXXX. Se a licença foi emitida há mais de 72 horas e nunca foi ativada, ela expira — peça reemissão no painel.

"NanoShield bloqueou um comando legítimo"

A taxa de falso positivo medida em benchmark é inferior a 5 por cento, mas não é zero. Você pode inspecionar qual padrão casou via ironshell audit last. Se o padrão for genuinamente uma correção, abra uma issue com o comando e o ambiente — o corpus ALLOW é extensível e PRs são aceitos rapidamente.

"Agent parece travado sem resposta"

Geralmente é o provedor LLM com rate limit ou latência alta. Rode ironshell doctor para um diagnóstico completo: conectividade, saldo de budget por provedor, estado do cache local, integridade do runtime e compatibilidade com o Claude Code instalado. Se o provedor principal estiver indisponível, o SmartRouter sugere alternativas com base no seu .env.

"Permissão negada ao escrever em ~/.ironshell"

Em Linux e macOS, o cliente pede permissão 700 no diretório. Se um processo anterior criou com permissão mais aberta, rode chmod 700 ~/.ironshell e tente de novo. Em Windows, o diretório fica em %APPDATA%\IronShell.

"Instalação falha em WSL1"

O IronShell usa recursos de filesystem que o WSL1 não implementa corretamente. Migre para WSL2 — a Microsoft documenta o processo em wsl --set-version <distro> 2.

Próximos passos

Com a instalação feita e o primeiro comando executado, os próximos passos dependem do seu perfil.

  • Desenvolvedor explorando — abra a arquitetura para entender os componentes.
  • CTO avaliando — vá direto para segurança e benchmarks.
  • Platform engineer — deployment e integrações cobrem self-host e CI/CD.
  • Red team — FAQ tem a seção de bypass disclosure e programa de bounty.