Guia de instalação

Instale o Nirvana-OS e converse com o seu agente.

O Nirvana-OS vive dentro do agente de IA que você já usa (Claude Code, Codex, Antigravity, Pi e outros). Você instala o engine uma vez, instala um pacote se quiser conteúdo pronto, prepara a pasta do projeto e, daí em diante, só conversa. O agente é quem roda os comandos.

Estável · 0.14.11

Para todo mundo. É o que o comando padrão instala, e é o canal deste guia.

Beta · v0.15.0-beta.12

Para quem quer as mudanças da 0.15 agora. O comando de cada sistema está abaixo; o que muda está na página do beta.

1. Instale o engine

Escolha o seu sistema. Cada aba tem o que preparar, o comando da versão estável e o comando do beta. O instalador baixa o Bun na sua pasta de usuário se ele faltar (sem sudo e sem administrador). Node não é necessário. Rodar de novo é seguro.

macOS

Antes

Nada a preparar: o macOS já traz curl e tar. Abra o Terminal (Aplicativos, Utilitários, Terminal).

Estável

curl -fsSL https://gutomec.github.io/nirvana-os-engine/install.sh | bash

Beta v0.15.0-beta.12

curl -fsSL https://gutomec.github.io/nirvana-os-engine/install.sh | NIRVANA_ENGINE_URL=https://github.com/gutomec/nirvana-os-engine/releases/download/v0.15.0-beta.12/nirvana-os-engine.tar.gz bash

Depois

Feche o Terminal e abra de novo, para o comando nrv entrar no PATH. Confira com nrv --version. Ao fechar, o Terminal pode mostrar "Saving session… [Processo concluído]": é normal, não é erro.

Windows

Antes

Windows 10 ou 11, sem precisar de administrador. Abra o PowerShell pelo menu Iniciar.

Estável

irm https://gutomec.github.io/nirvana-os-engine/install.ps1 | iex

Beta v0.15.0-beta.12

É uma linha só. Cole inteira e aperte Enter:

$env:NIRVANA_ENGINE_URL='https://github.com/gutomec/nirvana-os-engine/releases/download/v0.15.0-beta.12/nirvana-os-engine.tar.gz'; irm https://gutomec.github.io/nirvana-os-engine/install.ps1 | iex

Se a janela continuar aberta no fim, rode:

Remove-Item Env:NIRVANA_ENGINE_URL

Enquanto essa variável existir na janela, o nrv update e o setup de pacotes reinstalam o beta fixado. Os comandos usam aspas simples de propósito: uma aspa dupla perdida na colagem (um app de mensagens pode cortá-la) deixa o PowerShell parado em >>.

Depois

Feche o PowerShell e abra um novo. Confira com nrv --version.

Windows com WSL (Ubuntu)

O WSL roda o Ubuntu dentro do Windows. Se você escolher esse caminho, tudo fica dentro do Ubuntu: o Nirvana-OS e também o seu agente de IA.

Antes

Abra o PowerShell como administrador (botão direito no ícone, Executar como administrador) e rode:
```
wsl --install
```
Reinicie o computador quando ele pedir.
Abra o app Ubuntu no menu Iniciar e crie o seu usuário e a sua senha do Linux.

No Ubuntu, instale o que o instalador precisa:

sudo apt update && sudo apt install -y curl unzip

Estável

curl -fsSL https://gutomec.github.io/nirvana-os-engine/install.sh | bash

Beta v0.15.0-beta.12

curl -fsSL https://gutomec.github.io/nirvana-os-engine/install.sh | NIRVANA_ENGINE_URL=https://github.com/gutomec/nirvana-os-engine/releases/download/v0.15.0-beta.12/nirvana-os-engine.tar.gz bash

Depois

Feche o Ubuntu e abra de novo. Confira com nrv --version.
Instale o seu agente de IA (Claude Code, Codex, Antigravity) dentro do Ubuntu. Um agente instalado do lado do Windows não enxerga o engine que está no Ubuntu.
Guarde os projetos na sua pasta do Ubuntu (~), não em /mnt/c. Arquivos em /mnt/c passam pelo sistema de arquivos do Windows e ficam bem mais lentos.

Linux (Ubuntu)

Antes

O instalador do Bun precisa do unzip, e os pacotes chegam em zip:

sudo apt update && sudo apt install -y curl unzip

Estável

curl -fsSL https://gutomec.github.io/nirvana-os-engine/install.sh | bash

Beta v0.15.0-beta.12

curl -fsSL https://gutomec.github.io/nirvana-os-engine/install.sh | NIRVANA_ENGINE_URL=https://github.com/gutomec/nirvana-os-engine/releases/download/v0.15.0-beta.12/nirvana-os-engine.tar.gz bash

Depois

Feche o terminal e abra um novo. Confira com nrv --version.

Sobre a tag do beta. Ela começa com v (v0.15.0-beta.12). Sem o v, ou com uma versão que não existe, o download devolve 404. As versões publicadas estão na lista de releases.

O que o instalador muda na sua máquina

o engine em ~/.nirvana/skills e as bibliotecas dele em ~/.nirvana/node_modules;
a skill nirvana ligada em cada agente que encontrar (~/.claude/skills, ~/.codex/skills, ~/.gemini/config/skills do Antigravity, ~/.pi/agent/skills, ~/.agents/skills);
nrv em ~/.local/bin, com uma linha de PATH no perfil do shell (no Windows, o PATH do usuário);
hooks de auditoria no Claude Code, no Antigravity e no Codex;
as pastas de conteúdo vazias ~/squads, ~/businesses e ~/businesses/_library/dna.

Para conferir, peça ao agente "confira se o Nirvana-OS está instalado corretamente" ou rode nrv doctor.

2. Instale um pacote do squads.sh

O engine vem sem conteúdo: você pode criar empresas, squads e mind-clones conversando com o agente, ou comprar um pacote pronto no squads.sh. O exemplo aqui é o Genesis Circle; todo pacote se instala do mesmo jeito.

Baixe o zip pelo seu painel no squads.sh. Depois descompacte o arquivo inteiro, abra um terminal na pasta que tem o setup.sh e o setup.ps1, e rode o setup:

macOS

No Finder, dê dois cliques no zip baixado. Ele vira uma pasta ao lado.
No Terminal, digite cd e um espaço, arraste a pasta para a janela do Terminal e aperte Enter.
Rode o setup:
```
bash setup.sh
```

Windows

Clique com o botão direito no zip e escolha Extrair tudo.
Abra a pasta extraída (a que tem o setup.ps1), clique com o botão direito num espaço vazio e escolha Abrir no Terminal. No Windows 10, segure Shift ao clicar e escolha Abrir janela do PowerShell aqui.

Rode o setup:

powershell -ExecutionPolicy Bypass -File setup.ps1

Windows com WSL

O navegador do Windows salva o zip em /mnt/c/Users/<usuário>/Downloads. No Ubuntu, copie para dentro do Linux (troque <usuário> pelo seu usuário do Windows e <arquivo> pelo nome do zip):
```
mkdir -p ~/Downloads && cp /mnt/c/Users/<usuário>/Downloads/<arquivo>.zip ~/Downloads/
```

Descompacte e entre na pasta:

cd ~/Downloads && unzip <arquivo>.zip -d <pasta> && cd <pasta>

Rode o setup:
```
bash setup.sh
```

Linux

Descompacte e entre na pasta (troque <arquivo> pelo nome do zip e <pasta> por um nome à sua escolha, como genesis-circle):
```
cd ~/Downloads && unzip <arquivo>.zip -d <pasta> && cd <pasta>
```
Rode o setup:
```
bash setup.sh
```

O que o setup faz

instala o Bun se faltar, e o engine se ele ainda não existir; se existir, atualiza no mesmo canal;
copia o conteúdo para ~/squads/<pacote>, ~/businesses/<pacote> e ~/businesses/_library/dna/<pacote> (os mind-clones);
reconstrói os índices de roteamento;
guarda a licença em ~/.nirvana-license/packs/<pacote>/, que o nrv update <pacote> usa depois.

O setup de um pacote nunca troca o engine por uma versão mais antiga. Quem está no beta continua no beta (no máximo vai para um beta mais novo ou para a estável que vier depois dele). Essa regra está no setup dos pacotes gerados a partir do engine 0.14.11; se o seu zip é mais antigo, baixe o pacote de novo.

Pronto. Peça ao agente: "Use o Nirvana para listar o que o pacote Genesis Circle me trouxe."

3. Prepare um projeto

Todo trabalho acontece numa pasta de projeto. Abra a pasta, inicie o agente nela e diga "prepare esta pasta como um projeto do Nirvana-OS". Ele roda:

nrv init .

O nrv init cria .nirvana/project.yaml, as pastas de trabalho e as instruções para o agente em AGENTS.md, CLAUDE.md e GEMINI.md. Se esses arquivos já existem, as suas linhas ficam; o bloco do Nirvana entra marcado. Os entregáveis caem em outputs/, dentro do projeto.

O comportamento padrão é diferente em cada canal:

	Estável 0.14.11	Beta 0.15
Padrão	`always`: o Nirvana orquestra todo entregável concreto do projeto	`on-demand`: o agente trabalha como sempre e usa o Nirvana só quando o pedido chama por ele
Pergunta?	Só quando você roda o comando num terminal e a pasta já tem `AGENTS.md`, `CLAUDE.md` ou `GEMINI.md`; recomenda sob demanda. Rodado pelo agente, ou numa pasta sem esses arquivos, usa `always`	Nunca
Outro modo	`nrv init . --orchestrators=on-demand`	`nrv init . --orchestrators=always`

Sob demanda, o pedido chama o Nirvana quando nomeia o Nirvana ("use o Nirvana para…"), nomeia uma das suas empresas, squads ou mind-clones, ou pede trabalho em outro runtime ("use o Codex para revisar"). Para escolher pelo agente, diga "prepare esta pasta como projeto do Nirvana, só sob demanda" ou "orquestre tudo neste projeto com o Nirvana".

4. Converse com o seu agente

No dia a dia você não digita comandos do nrv. Você pede em linguagem natural e o agente usa o Nirvana-OS: escolhe as empresas e os squads, escreve um brief para cada um, despacha e devolve o resultado com a trilha de auditoria no disco.

"Quais empresas, squads e mind-clones eu tenho?"

"Use o Nirvana para escrever a copy de lançamento do meu curso."

"Use as empresas do Genesis Circle para criar uma landing page e uma análise da concorrência da marca X."

"Rode isso pelo squad de copy, no Codex."

"Troque o título do que você entregou."

"Mostre o que essa execução fez."

5. Ative os squads na primeira vez

Alguns squads usam ferramentas de verdade: ffmpeg, uma biblioteca Python, um navegador, um modelo baixado, uma API. Ativar instala e confere tudo isso antes. Peça ao agente:

"Ative todos os meus squads do Nirvana."

"Instale as dependências de todos os squads."

"Prepare o squad de vídeo."

O agente roda nrv activate --all (ou nrv activate <squad>). Quando algo falha, ele recebe uma lista com o squad, o que falta, o erro e o comando exato que corrige cada item. Ele roda as correções seguras e pede a sua permissão antes de qualquer coisa que use brew, sudo ou winget, e antes de qualquer chave de API, que só você pode fornecer (no ambiente ou no .env do projeto).

A ativação cobre:

o ambiente Node e Python de cada squad, em ~/.nirvana/envs/<squad>. O primeiro despacho de um squad já prepara o dele; ativar só adianta isso;
programas do sistema, como o ffmpeg, pelo gerenciador de pacotes;
chaves de API e variáveis de ambiente que o squad precisa;
servidores MCP e modelos (downloads grandes pedem confirmação).

Num pacote grande, o primeiro --all leva alguns minutos; depois, só confere. Se você mesmo rodar nrv activate --all num terminal, ele mostra um resumo e oferece entregar as falhas a um agente instalado para corrigir.

6. Atualize

O engine

Peça "atualize o Nirvana-OS" ou rode:

nrv update

Ele faz backup de ~/.nirvana/skills antes e mantém o seu conteúdo e as suas configurações. nrv update --check só diz qual versão instalaria. Uma atualização nunca leva o engine para uma versão mais antiga: a estável só vai para uma estável mais nova; o beta vai para o beta mais novo ou para a estável que vier depois dele, e nunca volta para a 0.14.

Um pacote

Peça "atualize o meu pacote Genesis Circle" ou rode nrv update com o slug do pacote:

nrv update genesis-circle

Os componentes que você editou ganham backup em ~/.nirvana/backups/packs/<pacote>/ antes de serem substituídos. Se aparecer erro de licença, baixe o pacote de novo no squads.sh e rode o setup outra vez: isso reinstala a licença.

Do beta para a estável

O passo a passo está na página do beta.

7. Configure os briefs do projeto

Duas coisas definem o que o seu agente entrega às empresas que ele despacha. Os templates existem a partir do beta 0.15.0-beta.11. Na versão estável (0.14.x), o nível de detalhe do brief se escolhe com nrv config set briefing.altitude <outcome|guided|prescriptive> --project.

O template do brief

O orquestrador escreve cada brief com um template: um arquivo markdown com a instrução e o esqueleto. O engine traz quatro:

Template	O que o brief leva
`slim` (padrão)	linhas curtas com rótulo: Goal, Request (o caminho de um arquivo com as palavras do usuário, sem edição), Decisions, Inputs, Deliver, Done when e Session
`standard`	as seis seções: Request verbatim, Decisions, Your part, Inputs, Done when e Output
`detailed`	as seis seções, mais a estrutura sugerida e o método, um critério por item e cada artefato nomeado
`karpathy`	o slim mais uma explicação de volta: um resumo em linguagem simples, um diagrama e, quando ajuda, uma página HTML explicativa. Inspirado no post de Andrej Karpathy no X e no 2025 Year in Review dele. Gasta mais tokens por entrega, por isso nunca é o padrão

Escolha um por projeto, gravado em .nirvana/config.yaml (rode dentro de um projeto preparado com nrv init):

nrv config set briefing.template detailed --project

nrv brief templates

Um template seu

Copie um template e edite a cópia. No projeto ela fica em .nirvana/brief-templates/; com --global, em ~/.nirvana/brief-templates/, para todos os projetos:

nrv brief init juridico --from standard --project

nrv config set briefing.template juridico --project

Um nome é procurado primeiro no projeto, depois na pasta global e por último no engine, então dá para trocar o slim num projeto só. Mantenha os rótulos que a lista required do arquivo nomeia (no mínimo Request e Done when): o engine lê esses rótulos. A antiga briefing.altitude continua valendo como apelido obsoleto enquanto briefing.template estiver vazio: outcome vira standard e prescriptive vira detailed.

Regras do projeto em texto livre

Escreva no CLAUDE.md, AGENTS.md ou GEMINI.md do projeto (o que o seu agente lê), acima da primeira linha que começa com <!-- nirvana-os:. Dali para baixo é o bloco do Nirvana, que o nrv init reescreve quando o texto do engine muda. O agente lê esses arquivos ao abrir a sessão e leva as suas regras para os briefs que escreve.

Em linguagem natural:

"Neste projeto, use briefs detalhados."

"Acrescente ao CLAUDE.md deste projeto, acima do bloco do Nirvana: todo entregável em português do Brasil, com fontes datadas."

8. Solução de problemas

O PowerShell mostra >> e fica esperando: Uma aspa ficou aberta, quase sempre porque a aspa de fechamento se perdeu na colagem. Aperte Ctrl+C (ou feche a janela e abra outra) e cole de novo a linha única, exatamente como está nesta página.
O macOS mostra "Saving session… [Processo concluído]": Aparece quando você fecha o Terminal. É o Terminal encerrando o shell, não um erro.
A instalação do beta devolve 404: A tag está sem o v do começo (v0.15.0-beta.12) ou a versão não existe. Confira na lista de releases.
nrv: command not found: O terminal ainda não tem ~/.local/bin no PATH. Feche e abra um novo. Se continuar, acrescente export PATH="$HOME/.local/bin:$PATH" ao perfil do seu shell (macOS, Linux e WSL).
O Bun não instala no Ubuntu ou no WSL: Falta o unzip. Rode sudo apt update && sudo apt install -y curl unzip e o comando de instalação de novo.
Erro de licença ao atualizar um pacote: Baixe o pacote de novo no seu painel do squads.sh, descompacte e rode o setup: ele reinstala a licença. O nrv license install procura a licença em Downloads, na Área de Trabalho e na pasta atual. Se o setup rodou num terminal de administrador, atualize com esse mesmo usuário.
O agente não enxerga o Nirvana no WSL: O agente precisa estar instalado dentro do Ubuntu, junto com o engine. Abra o agente pelo Ubuntu, numa pasta em ~.
Outra coisa parece errada: nrv doctor confere runtimes, hooks, links das skills, dependências, índices e licenças (saída 1 são só avisos). nrv install --check confere os hooks e o PATH. Não reinstale só porque o doctor saiu com 1.

A referência completa, em inglês, está no INSTALL.md.