Installation

Five ways to get OpenCrabs running.

Quick install (Linux and macOS)

The fastest path. One command resolves the latest release, checks your platform, verifies the download against the published SHA256SUMS, installs opencrabs and the rtk helper, and installs the system libraries the Linux build needs.

curl -fsSL https://opencrabs.com/install.sh | bash

On Windows, use PowerShell:

iwr -useb https://opencrabs.com/install.ps1 | iex

It installs to /usr/local/bin when that directory is writable, otherwise to ~/.local/bin, and prints the export PATH line when the target is not on your PATH yet. It refuses to install when glibc is older than 2.38 (Ubuntu 24.04+, Debian 13+, Fedora 39+) or when the system uses musl, and it names the package to install instead of failing silently.

Flags go after bash -s -- when you pipe the script:

Both scripts are plain shell and PowerShell, readable before you run them: install.sh and install.ps1.

Opción 1: Homebrew (recomendado en macOS y Linux)

brew install opencrabs

OpenCrabs is in homebrew-core. Homebrew ships prebuilt bottles for Apple Silicon Macs (macOS 15 and newer) and for Linux amd64 and arm64, so no Rust toolchain is needed there. On an Intel Mac, Homebrew builds it from source instead; use the macos-amd64 release binary if you’d rather skip the build.

Ejecuta opencrabs tras instalar. Va directo al chat con su provider incorporado ya activo, así que el crab te saluda y puedes empezar a hablar. Ejecuta opencrabs --onboard cuando quieras el asistente de configuración.

Opción 2: Descargar Binario (todas las plataformas)

Descarga un binario precompilado desde GitHub Releases.

Linux (amd64)

sudo apt update && sudo apt install -y curl jq libgomp1
TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-linux-amd64.tar.gz" | tar xz
./opencrabs

Linux (arm64)

sudo apt update && sudo apt install -y curl jq libgomp1
TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-linux-arm64.tar.gz" | tar xz
./opencrabs

macOS (arm64 / Apple Silicon)

TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-macos-arm64.tar.gz" | tar xz
./opencrabs

Windows

$tag = (Invoke-RestMethod https://api.github.com/repos/opencrabs/opencrabs/releases/latest).tag_name
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://github.com/opencrabs/opencrabs/releases/download/$tag/opencrabs-$tag-windows-amd64.zip" -OutFile opencrabs.zip -UseBasicParsing
Expand-Archive opencrabs.zip -DestinationPath . -Force
.\opencrabs.exe

Va directo al chat con su provider incorporado ya activo. Ejecuta opencrabs --onboard cuando quieras el asistente de configuración.

Windows es una plataforma de primera clase (v0.5.3): manejo de shell consciente de la plataforma, lectura BOM/UTF-16 y fallbacks de tilde/cwd integrados, y CI compila Windows en cada PR (#627).

Verifica tu descarga (opcional): cada release publica un archivo SHA256SUMS junto a los tarballs.

Permisos de terminal necesarios. OpenCrabs lee/escribe brain files, config y archivos de proyecto. Tu app de terminal necesita acceso al sistema de archivos o el SO bloqueará las operaciones.

SO	Qué hacer
macOS	Ajustes del Sistema → Privacidad y Seguridad → Acceso a Disco Completo → activa tu app de terminal (Alacritty, iTerm2, Terminal, etc.). Si no aparece, pulsa “+” y añádela desde /Applications/. Sin esto, macOS pregunta repetidamente “quiere acceder a datos de otras apps”.
Windows	Ejecuta tu terminal (Windows Terminal, PowerShell, cmd) como Administrador en la primera ejecución, o concede a la terminal acceso de escritura a %USERPROFILE%\.opencrabs\ y a tus directorios de proyecto. Windows Defender también puede preguntar, pulsa “Permitir”.
Linux	Asegúrate de que tu usuario es dueño de ~/.opencrabs/ y de los directorios de proyecto. En sistemas con SELinux/AppArmor, el proceso de la terminal necesita acceso de lectura/escritura a esas rutas. Las terminales Flatpak/Snap pueden necesitar --filesystem=home o un permiso equivalente.

/rebuild funciona incluso con binarios precompilados: clona el código fuente a ~/.opencrabs/source/ en el primer uso, luego compila y reinicia en caliente.

Opción 3: Compilar desde Código Fuente

Necesario para /rebuild, añadir herramientas personalizadas o modificar el agente.

Configuración rápida (recomendada)

El script de configuración detecta automáticamente tu plataforma (macOS, Debian/Ubuntu, Fedora/RHEL, Arch) e instala todas las dependencias de build + Rust:

# Install all dependencies
curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/src/scripts/setup.sh | bash

# Clone and build
git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

Configuración manual

Si prefieres instalar las dependencias tú mismo:

• Rust stable: Instala Rust. La toolchain estable funciona desde v0.2.85
• Una clave API de al menos un proveedor soportado
• SQLite (incluido vía rusqlite)
• macOS: brew install cmake pkg-config
• Debian/Ubuntu: sudo apt install build-essential pkg-config libssl-dev cmake
• Fedora/RHEL: sudo dnf install gcc gcc-c++ make pkg-config openssl-devel cmake
• Arch: sudo pacman -S base-devel pkg-config openssl cmake

git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

OpenCrabs usa keys.toml en vez de .env para las claves API. El asistente de onboarding te ayudará a configurarlo, o edita ~/.opencrabs/keys.toml directamente.

Opción 4: Docker

Ejecuta OpenCrabs en un contenedor aislado. La build tarda ~15min (release de Rust + LTO).

git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
docker compose -f src/docker/compose.yml up --build

La config, el workspace y la BD de memoria persisten en un volumen Docker entre reinicios. Las claves API de keys.toml se montan en el contenedor en tiempo de ejecución, nunca se hornean en la imagen.

Autoarranque al Encender

Mantén OpenCrabs corriendo como daemon en segundo plano que arranca con tu sistema.

Linux (systemd)

The binary writes the unit itself, so the file cannot drift from the version you are running:

opencrabs service install

That writes ~/.config/systemd/user/opencrabs.service with Type=simple and OOMPolicy=continue, then reloads systemd. Start it with opencrabs service start: a user unit does not come back after a reboot unless lingering is enabled (see below), while a system-wide unit is enabled so it does. OOMPolicy=continue matters because the daemon is the parent of every tool call and cron child: without it, one child killed by the OOM killer stops the whole unit and takes every agent lane with it. The unit name carries the profile when you are not on default, as opencrabs-<profile>.service.

On a headless SSH session the per-user systemd bus is often missing, and the command fails with Failed to connect to bus. Enable lingering so the user service runs without a login, or install a system-wide unit instead:

sudo loginctl enable-linger $(whoami)
# or
sudo opencrabs service install

Manage the daemon with opencrabs service start|stop|restart|status, or with systemctl directly.

Comprueba el estado: systemctl --user status opencrabs | Logs: journalctl --user -u opencrabs -f

macOS (launchd)

cat > ~/Library/LaunchAgents/com.opencrabs.agent.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.opencrabs.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/opencrabs</string>
        <string>daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/opencrabs.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/opencrabs.err</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.opencrabs.agent.plist

Actualiza la ruta en ProgramArguments para que coincida con tu ubicación de instalación.

Windows (Programador de Tareas)

1. Win + R → taskschd.msc
2. Crear tarea básica → Nombre: OpenCrabs
3. Desencadenador: Al iniciar sesión
4. Acción: Iniciar un programa → C:\Users\<you>\.cargo\bin\opencrabs.exe, Argumentos: daemon
5. En Propiedades > Configuración, marca Si la tarea falla, reiniciar cada 1 minuto

O vía PowerShell:

$action = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.cargo\bin\opencrabs.exe" -Argument "daemon"
$trigger = New-ScheduledTaskTrigger -AtLogon
$settings = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName "OpenCrabs" -Action $action -Trigger $trigger -Settings $settings

Actualizando

• Usuarios de Homebrew: brew upgrade opencrabs (si escribes /evolve en una instalación Homebrew, delega en Homebrew, el binario sigue gestionado por brew, y el tap antiguo queda retirado en favor de los autobumps de homebrew-core)
• Usuarios de binario: Escribe /evolve en la TUI para descargar el último release
• Usuarios de código fuente: git pull && cargo build --release, o escribe /rebuild en la TUI
• Usuarios de Docker: docker compose pull && docker compose up -d