QUICK INSTALLATION GUIDE

Version: 1.0.0 | March 2026

This guide takes you step by step from download to your first conversation with Fararoni. Estimated time: 5-10 minutes.

Fararoni is distributed as native binaries compiled with GraalVM Native Image. You don't need Java installed to use Fararoni — the core and sidecars are standalone executables that don't require JVM or Node.js.

You only need one thing:

Ollama (LLM model server)

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# Download from: https://ollama.com/download/windows

Start Ollama and download a model:

# Start Ollama (leave it running)
ollama serve

# In another terminal, download a model
ollama pull qwen2.5-coder:7b

Download the installer for your platform from GitHub Releases:

Or with Homebrew:

brew tap ebercruzf/fararoni
brew install fararoni

1. Open Fararoni-Installer-macos-arm64.dmg
2. Double-click "Install Fararoni.command"

If macOS blocks execution: right-click > Open > Open.

A terminal opens and the installer detects it's running from the DMG:

  Detected: Running from disk image (DMG).
  The installer needs a writable disk.

  Copying Fararoni Suite to: /Users/your-user/Fararoni ...
  Copied. Starting installer...

Then the banner appears and the interactive wizard begins.

The installer checks your system automatically:

[1/5] Verificando requisitos...
[OK] Sistema: macOS (arm64)
[OK] Core nativo: fararoni-core
[OK] Sidecars nativos detectados en bin/

You don't need to do anything, just wait.

[2/5] Registrando Core como servicio del sistema...
  El Core se ejecutara como servicio de fondo (auto-start, auto-restart).
  Registrar como servicio? (s/n):

Type s and press Enter (recommended).

The installer creates the file ~/Library/LaunchAgents/com.fararoni.core.plist.

[3/5] Instalando comando global 'fararoni'...
[OK] Symlink: /Users/your-user/bin/fararoni -> /Users/your-user/Fararoni/bin/fararoni-core
[WARN] /Users/your-user/bin no esta en tu PATH.
  Agrega a ~/.zshrc:  export PATH="/Users/your-user/bin:$PATH"

If the PATH warning appears, after installation run:

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

The installer asks about each messaging channel one by one. If you're not going to use a channel, answer n to skip it.

[4/5] Configurando Sidecars (binarios nativos)...

  Canales disponibles:

Telegram

  [1] Activar Telegram (Puerto 3001)? (s/n): s

  Credencial requerida: Token de BotFather para Telegram
  Documentacion: https://core.telegram.org/bots#how-do-i-create-a-bot
    1) Configurar ahora
    2) Configurar despues (no arranca)
    3) Arrancar sin credencial
  Opcion [1-3]: 3
[WARN] Telegram arrancara sin credencial.
[OK] Telegram: LaunchAgent creado

WhatsApp

  [2] Activar WhatsApp (Puerto 3000)? (s/n): s
[OK] WhatsApp: LaunchAgent creado

WhatsApp doesn't ask for credentials — it uses a QR code when starting the sidecar.

Discord

  [3] Activar Discord (Puerto 3002)? (s/n): s

  Credencial requerida: Token del Bot en Developer Portal
  Documentacion: https://discord.com/developers/applications
    1) Configurar ahora
    2) Configurar despues (no arranca)
    3) Arrancar sin credencial
  Opcion [1-3]: 3
[WARN] Discord arrancara sin credencial.
[OK] Discord: LaunchAgent creado

iMessage (macOS only)

  [4] Activar iMessage (Puerto 3003)? (s/n): s

  Credencial requerida: Password del servidor BlueBubbles
  Documentacion: Requiere BlueBubbles Server en macOS
    1) Configurar ahora
    2) Configurar despues (no arranca)
    3) Arrancar sin credencial
  Opcion [1-3]: 3
[WARN] iMessage arrancara sin credencial.
[OK] iMessage: LaunchAgent creado

Credential options

For each channel that requires credentials, the installer offers 3 options:

If you don't have credentials yet, type 2 or 3 — you can configure them later by editing the .env files in ~/Fararoni/config/ or using the /config set command from the CLI.

Upon completion, the full summary is shown:

[5/5] Instalacion completada

  ==================================================================
              FARARONI SUITE v1.0.0 — OPERATIVO
  ==================================================================

  CORE (GraalVM Native):
    Binario:     /Users/your-user/Fararoni/bin/fararoni-core
    Comando:     fararoni --server
    Servicio:    launchctl load ~/Library/LaunchAgents/com.fararoni.core.plist
    Logs:        tail -f /Users/your-user/Fararoni/logs/core.log

  SIDECARS (Nativos SEA):
    telegram:  /Users/your-user/Fararoni/logs/sidecar-telegram-out.log
    whatsapp:  /Users/your-user/Fararoni/logs/sidecar-whatsapp-out.log
    discord:   /Users/your-user/Fararoni/logs/sidecar-discord-out.log
    imessage:  /Users/your-user/Fararoni/logs/sidecar-imessage-out.log

    Iniciar:     launchctl load ~/Library/LaunchAgents/com.fararoni.sidecar-*.plist
    Detener:     launchctl unload ~/Library/LaunchAgents/com.fararoni.sidecar-*.plist

  COMANDOS RAPIDOS:
    fararoni --version        Verificar
    fararoni                  CLI interactivo
    fararoni --server         Servidor (REST + Gateway)
    ./fararoni-launcher.sh    Iniciar todo (core + sidecars)

  ==================================================================
    Fararoni v1.0.0 instalado. Sistema operativo.
  ==================================================================

Quick Commands (reference)

At the end you'll see:

Saving session...
...copying shared history...
...saving history...truncating history files...
...completed.

[Process completed]

This is normal. The terminal becomes unresponsive (doesn't respond to Enter or Ctrl+C). Simply close that window with Cmd+W and open a new terminal.

Open a new terminal and type:

fararoni

If the command is not found, add the PATH first:

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Fararoni detects it's your first time and launches an interactive wizard:

fararoni
[KERNEL] Iniciando Fararoni en: /Users/your-user
[WorkspaceManager] Initialized: /Users/your-user/.llm-fararoni (User Home Default)

========================================
     FARARONI - Primera Ejecucion
========================================

Bienvenido a FARARONI!

Parece que es tu primera vez usando esta herramienta.
Vamos a configurar los ajustes basicos.

Puedes omitir este proceso presionando Ctrl+C
y configurar manualmente despues.

¿Como quieres usar FARARONI?

  ✓ Ollama detectado en localhost:11434

  [1] Solo servidor externo (Ollama)
      → Usa solo el modelo grande de Ollama

  [2] Hibrido: Ollama + Motor local (Recomendado)
      → Modelo grande (Ollama) + modelo pequeño local como fallback
      → El motor local se usa para routing y cuando Ollama no esta disponible

  [3] Solo modo local (100% offline)
      → Todo local, funciona sin internet (~1.2 GB)

  [0] Omitir configuracion

Tu eleccion [1/2/3/0]:

Type 2 and press Enter (tested and recommended).

PASO 1/4: URL del Servidor

  ✓ Ollama detectado - usando http://localhost:11434

Server URL [http://localhost:11434]:
  → Servidor: http://localhost:11434

Press Enter to accept the default value (recommended). Only type a different URL if you have Ollama on another machine or port.

PASO 2/4: API Key

  Ollama no requiere API key. Presiona Enter para omitir.

API Key (opcional):
  → Sin API Key (no requerida)

Press Enter to skip. Ollama doesn't use an API key.

PASO 3/4: Modelo por Defecto

  Modelos populares: qwen2.5-coder:1.5b-instruct, qwen2.5-coder:7b, llama3.2

Modelo [qwen2.5-coder:1.5b-instruct]:

Press Enter to accept qwen2.5-coder:1.5b-instruct (default value, recommended). Only type another name if you want to use a different model already downloaded in Ollama.

After confirming it shows:

  → Modelo: qwen2.5-coder:1.5b-instruct

Since you chose option 2 (Hybrid), the wizard configures the local engine:

PASO 4/4: Motor Local (Fallback)

El motor local se usara para:
  • Routing inteligente de consultas
  • Fallback cuando el servidor no este disponible
  • Tareas simples sin necesidad de servidor

Se descargara cuando inicies FARARONI (~5 MB motor + ~1.2 GB modelo)

  → Modo hibrido activado

You don't need to do anything — it's configured automatically. The engine and local model download happens the first time you start Fararoni.

Technical note: The local engine uses ollama.cpp, a native inference library. Fararoni automatically detects your system architecture (arm64, x64) and downloads the compiled version specific to your platform. You don't need to configure anything manually.

========================================
     SEGURIDAD — Estrategia 3 Llaves
========================================

Fararoni protege tu sistema con 3 niveles:
  Llave 1: TOTP (Google Authenticator)
  Llave 2: Sandbox (carpeta de confianza)
  Llave 3: Master Password (elevacion sudo)

Canales externos (WhatsApp, Telegram) pediran
codigo 2FA. El CLI local NO lo requiere.

¿Configurar seguridad ahora? [S/n]:

Type s and press Enter (recommended). Security protects access from external channels and also allows you to elevate privileges with sudo.

Prerequisite: You need the Google Authenticator (or Authy) app installed on your phone. It's a free app that generates 6-digit codes every 30 seconds. Download it from App Store (iOS) or Google Play (Android).

After typing s, a QR code appears directly in the terminal:

=================================================================
  CONFIGURACION DE SEGURIDAD — 2FA (Google Authenticator)
=================================================================

  1. Abre Google Authenticator (o Authy) en tu celular
  2. Escanea este codigo directamente desde tu terminal:

       ██████████████        ██            ██  ████████
       ██          ██  ████████  ████████████  ██  ████
       ██  ██████  ██    ████████  ██████  ████  ████████
       ...

     CLAVE MANUAL: XXXX4K2ML7EQRLZBLJW6DLDN7H3WXXXX

  3. Fararoni te pedira el codigo de 6 digitos al conectar
     por WhatsApp, Telegram o cualquier canal externo.

=================================================================

  Codigo de 6 digitos de tu app:

Steps:

1. Open Google Authenticator on your phone
2. Tap + > Scan QR code
3. Point the camera at the QR displayed in your terminal
4. If you can't scan, use the manual key shown below the QR (enter it manually in the app as "setup key")
5. The app will show a 6-digit code that changes every 30 seconds
6. Type that code in the terminal and press Enter

This 6-digit code is your Key 1 (TOTP). Fararoni will ask for it every time you connect from an external channel (WhatsApp, Telegram, Discord, iMessage). Not required from the local CLI.

After verifying the code:

  Codigo de 6 digitos de tu app: ******
  → Codigo verificado correctamente

PASO 6: Master Password (elevacion de privilegios)

Este password permite acceso temporal fuera del Sandbox
usando 'sudo password' (sesion de 15 min).

  Master Password (min 8 chars):
  Confirmar password:
  → Master Password guardado (BCrypt)

Enter a password of at least 8 characters and confirm it.

This is your Key 3 (Master Password). It allows you to temporarily elevate privileges (15 minutes) so Fararoni can operate outside the trust folder (Sandbox). From the CLI it's used with the sudo your-password command.

PASO 7: Carpeta de Confianza (Sandbox)

El agente solo puede leer/escribir dentro de esta carpeta.
Todo lo externo requiere 'sudo' para acceder.

  Ruta de confianza [/Users/your-user/Documents/Proyectos]:

Press Enter to accept the default path, or type another path if your projects are in a different location.

This is your Key 2 (Sandbox). It defines the folder where Fararoni can operate freely: read files, write code, execute commands, etc. Any operation outside this folder requires elevating privileges with sudo password. This protects the rest of your system (personal documents, OS configuration, etc.) from accidental modifications by the agent.

After confirming the trust folder, Fararoni shows the summary:

  → Sandbox: /Users/your-user/Documents/Proyectos

----------------------------------------
  Seguridad configurada correctamente
----------------------------------------
  Llave 1 (TOTP):    Activa
  Llave 2 (Sandbox): Activa
  Llave 3 (BCrypt):  Configurada
----------------------------------------

Followed by the complete configuration summary:

========================================
     Configuracion Completada!
========================================

FARARONI esta listo para usar.

Comandos utiles:
  fararoni              - Iniciar shell interactivo
  fararoni config show  - Ver configuracion
  fararoni --help       - Ver ayuda

Que tengas una excelente experiencia!

Immediately after, Fararoni detects that local engine components are missing (because you chose option 2 — Hybrid) and offers to download them:

[BOOTSTRAP] Verificando componentes del motor neural...
   [X] Motor nativo: NO INSTALADO
   [X] Modelo local (1.5B): NO DESCARGADO

[WARN] ATENCION: Faltan componentes para el modo local.
   Para funcionar localmente, se necesita descargar:
   • Motor nativo (~5 MB)
   • Modelo Qwen 1.5B (~1.2 GB)

   ¿Deseas iniciar la descarga ahora? [S/n]:

Type S and press Enter. The download starts automatically:

[DOWNLOAD] Descargando motor nativo (~5 MB)...
   [OK] Motor descargado
   [OK] Motor nativo instalado

[DOWNLOAD] Descargando modelo Qwen 1.5B (~1.2 GB)...
   (Esto puede tomar varios minutos)
   Descargando: 2.9% (30.8 MB / 1.04 GB)

The native engine download is fast (~5 MB). The Qwen 1.5B model is larger (~1.2 GB) and may take several minutes depending on your internet connection. Wait for it to finish — you'll see a progress bar.

What gets downloaded? The native engine is ollama.cpp, an inference library that allows running LLM models locally without depending on the Ollama server. The Qwen 1.5B model is a small model used as fallback for routing and simple tasks when Ollama is not available.

Once the download completes, Fararoni starts all its subsystems:

[OK] Modelo descargado
[OK] Modelo local instalado

[OK] [BOOTSTRAP] Motor instalado y verificado.
Fararoni Online. Analizando territorio...

Fararoni scans your working directory and shows a summary:

============ CONCIENCIA SITUACIONAL ============
Proyecto Detectado: (project type)
Ubicacion: your-user
Archivos encontrados: (count)
------------------------------------------------
ESTRUCTURA DE ARCHIVOS:
...
================================================

Then it initializes all internal subsystems:

Inicializando subsistemas...
[FARARONI] Enlace primario estable.
[FARARONI]  Persistencia Blindada ACTIVA (Outbox Pattern: sovereign_bus.db)
[FARARONI]  Repositorio de canales inicializado
[FARARONI]  MessagingChannelManager iniciado
[FARARONI]  Security Auth ACTIVO (TOTP + Sandbox + BCrypt)
[FARARONI]  GalvanicAgent iniciado en Bus Soberano
[FARARONI]  QuartermasterAgent iniciado en Bus Soberano
[FARARONI]  AgentTemplateManager iniciado (10 agentes activos, LLM inyectado)
[FARARONI]  SovereignMissionEngine activo
[RECOVERY] Servicio de Recuperacion de Desastres iniciado
[SAFETY] FileSystemIntentListener activo (Write + Restore)
[TOOL-REGISTRY] Herramientas base: 36+
 Dynamic Tool Prompting activado

Don't worry about these messages — they're informational boot logs. The important thing is that no [ERROR] messages appear.

Finally the Fararoni banner appears with the active configuration:

╔═══════════════════════════════════════════════════════════════════════╗
║                                                                       ║
║  ███████╗ █████╗ ██████╗  █████╗ ██████╗  ██████╗ ███╗   ██╗██╗       ║
║  ██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔═══██╗████╗  ██║██║       ║
║  █████╗  ███████║██████╔╝███████║██████╔╝██║   ██║██╔██╗ ██║██║       ║
║  ██╔══╝  ██╔══██║██╔══██╗██╔══██║██╔══██╗██║   ██║██║╚██╗██║██║       ║
║  ██║     ██║  ██║██║  ██║██║  ██║██║  ██║╚██████╔╝██║ ╚████║██║       ║
║  ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝       ║
║                                                                       ║
║                   THE EXTRA COMPASS EDITION                           ║
║     Inspired by the legacy of: Crispin Fararoni Alfonso (C.F. I)      ║
║                                                                       ║
║                        FARARONI Core v1.0.0                           ║
║                         Open Source LLM CLI                           ║
╠═══════════════════════════════════════════════════════════════════════╣
║  CONFIGURACION ACTIVA:                                                ║
║  [>] Servidor: http://localhost:11434                     (config)    ║
║  [>] Modelo:   qwen2.5-coder:1.5b-instruct                (config)    ║
║  [>] Contexto: 32,768 tokens | Streaming: + | Tokenizer: REMOTE       ║
╠═══════════════════════════════════════════════════════════════════════╣
║  [i] Variables de entorno: LLM_SERVER_URL, LLM_MODEL_NAME, LLM_API_KEY║
║  [>] Configurar: fararoni config set key value                        ║
╚═══════════════════════════════════════════════════════════════════════╝

And the interactive prompt:

❯
── ▶▶ qwen2.5-coder:1.5b · Local | qwen2.5-coder:32b · Remote     Context: 0%

The bottom bar shows the two models and their status:

❯ hola

Fararoni: Hola! En que te ayudo?

❯
── ▶▶ qwen2.5-coder:1.5b · Local -A | qwen2.5-coder:32b · Remote -I

In this example, the Rabbit (Local) responds because it's a simple question. The bar shows Local -A (Active, in green) and Remote -I (Idle).

Fararoni automatically switches between models based on complexity:

The switch is automatic — you don't need to do anything. Rabbit responds in milliseconds for simple tasks, and when it detects the task is complex, it scales to Turtle automatically. You can also force the switch with /reconfig (Rabbit) or /reconfigt (Turtle).

Done! Fararoni is operational.

Now that you've verified Fararoni works, we suggest:

1. Close this terminal (type /exit or Ctrl+C)
2. Navigate to your trust folder (the one you configured in the Sandbox):

   cd ~/Documents/Proyectos

3. Start Fararoni again from there:

   fararoni

   This makes Fararoni analyze your actual project instead of the home directory.
4. If you want to configure WhatsApp or other channels, start in server mode:

   fararoni --server

   This starts the Core + Gateway, then in another terminal start the sidecar.

Type any question in English or Spanish:

fararoni> hello, analyze this project

fararoni> create a README.md file for my project

fararoni> explain what the Main.java class does

Useful commands

If you want Fararoni to respond via WhatsApp, Telegram, Discord or iMessage, you need to start the server and sidecars.

5.1 — Start Core in server mode

# Terminal 1 — native binary (no Java required)
fararoni --server

# Or with full path
~/Fararoni/bin/fararoni-core --server

This starts:

• Core Server on port 7070
• OmniChannel Gateway on port 7071 (automatic)

5.2 — Start a Sidecar

Each channel is an independent native binary (no Node.js required). Example with WhatsApp:

# Terminal 2
~/Fararoni/bin/sidecar-whatsapp

Scan the QR code with WhatsApp (Linked Devices > Link a Device).

Other channels:

# Telegram (needs @BotFather token)
export TELEGRAM_TOKEN="your_token"
~/Fararoni/bin/sidecar-telegram

# Discord (needs Developer Portal token)
export DISCORD_TOKEN="your_token"
~/Fararoni/bin/sidecar-discord

# iMessage (needs BlueBubbles)
export BLUEBUBBLES_PASSWORD="your_password"
~/Fararoni/bin/sidecar-imessage

5.3 — MCP Bridge (Model Context Protocol)

Fararoni includes an MCP sidecar (Model Context Protocol) that allows integrating external MCP servers with the ecosystem. Unlike the other sidecars (which are Node.js SEA binaries), the MCP Bridge is a Java module compiled with Maven.

# Compile the MCP sidecar
cd fararoni-sidecar-mcp
mvn clean package -DskipTests

# Run
java -jar target/fararoni-sidecar-mcp-1.0.0.jar

Status: Operational. Test results and detailed MCP server integration documentation coming soon.

To compile the MCP sidecar you do need Java 25+ (unlike the core and messaging sidecars which are native binaries).

# Ollama running?
curl http://localhost:11434/api/tags

# Core Server running?
curl http://localhost:7070/health

# Gateway running?
curl http://localhost:7071/health

# WhatsApp Sidecar running?
curl http://localhost:3000/health

If you exited before finishing configuration

If you closed the terminal or pressed Ctrl+C during the first-run wizard, Fararoni detects missing components and offers to continue:

fararoni
[KERNEL] Iniciando Fararoni en: /Users/your-user
[WorkspaceManager] Initialized: /Users/your-user/.llm-fararoni (User Home Default)

[BOOTSTRAP] Verificando componentes del motor neural...
   [X] Motor nativo: NO INSTALADO
   [X] Modelo local (1.5B): NO DESCARGADO

[WARN] ATENCION: Faltan componentes para el modo local.
   Para funcionar localmente, se necesita descargar:
   • Motor nativo (~5 MB)
   • Modelo Qwen 1.5B (~1.2 GB)

   ¿Deseas iniciar la descarga ahora? [S/n]:

Type S and press Enter to continue where you left off.

Reset configuration from scratch (without reinstalling)

Just delete the configuration folder and run fararoni again:

rm -rf ~/.llm-fararoni
fararoni

This restarts the first-run wizard. Binaries in ~/Fararoni/ are untouched.

Uninstall completely

To remove Fararoni entirely (binaries + configuration + data):

rm -rf ~/Fararoni
rm -rf ~/.fararoni
rm -rf ~/.llm-fararoni

If installed with Homebrew:

brew uninstall fararoni
brew untap ebercruzf/fararoni

Full guide available in the repository:
github.com/ebercruzf/fararoni-ecosystem — GUIA-INSTALACION-RAPIDA.md