Instale Node.js, Python, uv, Docker e obtenha suas chaves de API antes de começar.
O que é: Antes de instalar qualquer coisa, verifique se sua máquina atende aos requisitos mínimos. O MiroFish roda simulações que consomem CPU e memória, especialmente com muitos agentes.
Por que aprender: Hardware insuficiente causa travamentos, simulações que nunca terminam e erros de "out of memory". Validar antes evita frustração depois.
# Requisitos Mínimos de Hardware
RAM: 8 GB (16 GB recomendado)
CPU: 4+ cores (8+ cores recomendado)
Disco: 10 GB livres
GPU: Não necessária (LLM roda na nuvem)
# Sistemas Operacionais Suportados
Linux: Ubuntu 20.04+, Debian 11+, Fedora 38+
macOS: 12 Monterey+ (Intel ou Apple Silicon)
Windows: WSL2 com Ubuntu (nativo não suportado)
Dica: Em Windows, instale WSL2 primeiro com wsl --install no PowerShell como administrador.
O que é: Node.js é necessário para o frontend Vue.js, os scripts de build e os comandos npm. Use nvm (Node Version Manager) para instalar sem conflitos com o sistema.
Por que aprender: Sem Node.js, o frontend não compila e os scripts npm (como setup:all) não funcionam. nvm permite trocar de versão facilmente.
# 1. Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc # ou ~/.zshrc
# 2. Instalar Node.js 20 LTS
nvm install 20
nvm use 20
nvm alias default 20
# 3. Verificar instalação
node --version # v20.x.x
npm --version # 10.x.x
Node 18 é o mínimo, mas Node 20 LTS é recomendado por ser mais estável e ter suporte mais longo.
O que é: O backend Python requer versão 3.11 ou 3.12. Python 3.13+ NÃO é compatível com dependências do CAMEL-AI/OASIS. Use pyenv para gerenciar versões.
Por que aprender: A versão errada do Python é a causa número 1 de falhas na instalação. CAMEL-AI tem dependências que quebram no Python 3.13+.
# 1. Instalar pyenv
curl https://pyenv.run | bash
# Adicionar ao ~/.bashrc ou ~/.zshrc:
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
# 2. Instalar Python 3.12
pyenv install 3.12.7
pyenv global 3.12.7
# 3. Verificar
python --version # Python 3.12.7
⚠️ NÃO use Python 3.13+ - CAMEL-AI não é compatível!
O que é: uv é um gerenciador de pacotes Python escrito em Rust, 10-100x mais rápido que pip. O fork inematds usa uv para gerenciar dependências do backend.
Por que aprender: npm run setup:all depende do uv para instalar pacotes Python. Sem uv instalado, o setup falha na etapa do backend.
# Instalar uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Verificar instalação
uv --version # uv 0.x.x
# Comandos úteis do uv
uv venv # Criar ambiente virtual
uv pip install # Instalar pacote (compatível com pip)
uv sync # Sincronizar dependências do pyproject.toml
uv é da Astral (mesma empresa do ruff). Substitui pip, pip-tools, virtualenv e poetry em um único binário.
O que é: Docker containeriza a aplicação para deploy consistente. Docker Compose orquestra múltiplos serviços (app + Traefik). Essencial para produção.
Por que aprender: Docker é o método recomendado para deploy em produção. Para desenvolvimento local, é opcional (npm run dev funciona direto).
# Ubuntu/Debian - Instalar Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
# macOS - Instalar Docker Desktop
brew install --cask docker
# Verificar instalação
docker --version # Docker 24.x+
docker compose version # Docker Compose v2.x+
docker run hello-world # Teste rápido
O que é: O MiroFish precisa de acesso a um LLM. Você tem duas opções: usar Claude CLI/Codex CLI (sem API key, usa assinatura existente) ou obter API keys da OpenAI/Anthropic.
Por que aprender: Sem LLM configurado, o sistema não consegue gerar personas, simular agentes ou criar relatórios. É o pré-requisito mais importante.
# Opção 1: Claude CLI (GRATUITO com assinatura)
npm install -g @anthropic-ai/claude-code
claude # Autenticar na primeira execução
# Nenhuma API key necessária!
# Opção 2: API Key da OpenAI
# Acesse: https://platform.openai.com/api-keys
# Crie uma key: sk-proj-...
# Opção 3: API Key da Anthropic
# Acesse: https://console.anthropic.com/settings/keys
# Crie uma key: sk-ant-...
Recomendação: Comece com Claude CLI para testes (custo $0). Migre para API quando precisar de mais controle ou escala.