Skip to content

linux.md

Latest commit

 

History

History
311 lines (218 loc) · 6.98 KB

linux.md

File metadata and controls

311 lines (218 loc) · 6.98 KB
Raw

Guia de Instalação Linux para Synkra AIOX

🌐 EN | PT | ES

Distribuições Suportadas

Distribuição Versão Status
Ubuntu 20.04+ (LTS) ✅ Totalmente Suportado
Debian 11+ (Bullseye) ✅ Totalmente Suportado
Fedora 37+ ✅ Totalmente Suportado
Arch Linux Última ✅ Totalmente Suportado
Linux Mint 21+ ✅ Totalmente Suportado
Pop!_OS 22.04+ ✅ Totalmente Suportado
openSUSE Leap 15.4+ ⚠️ Testado pela Comunidade
CentOS/RHEL 9+ ⚠️ Testado pela Comunidade

Pré-requisitos

1. Node.js (v20 ou superior)

Escolha o método de instalação baseado na sua distribuição:

Ubuntu/Debian

# Atualizar lista de pacotes
sudo apt update

# Instalar Node.js usando NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verificar instalação
node --version  # Deve mostrar v20.x.x
npm --version

Alternativa: Usando nvm (Recomendado para desenvolvimento)

# Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Recarregar shell
source ~/.bashrc  # ou ~/.zshrc

# Instalar e usar Node.js 20
nvm install 20
nvm use 20
nvm alias default 20

Fedora

# Instalar Node.js dos repos do Fedora
sudo dnf install nodejs npm

# Ou usando NodeSource para versão mais recente
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

Arch Linux

# Instalar dos repos oficiais
sudo pacman -S nodejs npm

# Ou usando nvm (recomendado)
yay -S nvm  # Se usar helper AUR
nvm install 20

2. Git

# Ubuntu/Debian
sudo apt install git

# Fedora
sudo dnf install git

# Arch
sudo pacman -S git

# Verificar
git --version

3. GitHub CLI

# Ubuntu/Debian
(type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
&& sudo mkdir -p -m 755 /etc/apt/keyrings \
&& wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y

# Fedora
sudo dnf install gh

# Arch
sudo pacman -S github-cli

# Autenticar
gh auth login

4. Build Essentials (Opcional mas Recomendado)

Alguns pacotes npm requerem compilação:

# Ubuntu/Debian
sudo apt install build-essential

# Fedora
sudo dnf groupinstall "Development Tools"

# Arch
sudo pacman -S base-devel

Instalação

Instalação Rápida

  1. Abra seu terminal

  2. Navegue até o diretório do projeto:

    cd ~/projetos/meu-projeto

  3. Execute o instalador:

    npx github:SynkraAI/aiox-core install

O Que o Instalador Faz

O instalador automaticamente:

  • ✅ Detecta sua distribuição Linux e aplica otimizações
  • ✅ Cria diretórios necessários com permissões Unix apropriadas (755/644)
  • ✅ Configura caminhos de IDE para Linux:
    • Cursor: ~/.config/Cursor/
    • Claude: ~/.claude/
  • ✅ Configura scripts shell com terminações de linha Unix (LF)
  • ✅ Respeita a especificação XDG Base Directory
  • ✅ Lida com links simbólicos corretamente

Configuração Específica por IDE

Cursor

  1. Instale o Cursor: Baixe de cursor.sh

    # Método AppImage
chmod +x cursor-*.AppImage
./cursor-*.AppImage

  2. Regras da IDE são instaladas em .cursor/rules/

  3. Atalho de teclado: Ctrl+L para abrir chat

  4. Use @nome-do-agente para ativar agentes

Claude Code (CLI)

  1. Instale o Claude Code:

    npm install -g @anthropic-ai/claude-code

  2. Comandos são instalados em .claude/commands/AIOX/

  3. Use /nome-do-agente para ativar agentes

  4. Use @nome-do-agente para ativar agentes

Solução de Problemas

Erros de Permissão

# Corrigir permissões globais do npm (método recomendado)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Alternativa: Corrigir propriedade (se usar sudo para npm)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Erros EACCES

Se você ver EACCES: permission denied:

# Opção 1: Usar prefixo npm (recomendado)
npm config set prefix '~/.local'
export PATH="$HOME/.local/bin:$PATH"

# Opção 2: Corrigir permissões do projeto
chmod -R u+rwX .aiox-core
chmod -R u+rwX .claude

Problemas de Autenticação GitHub CLI

# Verificar status de autenticação atual
gh auth status

# Re-autenticar se necessário
gh auth login --web

# Para autenticação baseada em SSH
gh auth login -p ssh

Problemas Específicos do WSL

Se estiver rodando no Windows Subsystem for Linux:

# Garantir que caminhos Windows não interfiram
echo 'export PATH=$(echo "$PATH" | tr ":" "\n" | grep -v "^/mnt/c" | tr "\n" ":")' >> ~/.bashrc

# Corrigir problemas de terminação de linha
git config --global core.autocrlf input

# Performance: Mover projeto para sistema de arquivos Linux
# Use ~/projetos ao invés de /mnt/c/projetos

Atualização

Para atualizar uma instalação existente:

# Usando npx (recomendado)
npx github:SynkraAI/aiox-core install

O atualizador irá:

  • Detectar sua instalação existente
  • Fazer backup de customizações em .aiox-backup/
  • Atualizar apenas arquivos modificados
  • Preservar suas configurações

Requisitos do Sistema

Requisito Mínimo Recomendado
Kernel 4.15+ 5.10+
RAM 2GB 8GB
Espaço em Disco 500MB 2GB
Node.js 18.x 20.x LTS
npm 9.x 10.x

Próximos Passos

  1. Configure sua IDE (veja configuração específica por IDE acima)
  2. Execute *help no seu agente AI para ver comandos disponíveis
  3. Comece com o Guia do Usuário
  4. Junte-se à nossa Comunidade no Discord para ajuda

Recursos Adicionais