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.

Option 1 : Homebrew (recommandé sur macOS et 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.

Lancez opencrabs après l’installation. Il va directement dans le chat avec son provider intégré déjà actif, donc le crab vous salue et vous pouvez commencer à parler. Lancez opencrabs --onboard quand vous voulez l’assistant de configuration.

Option 2 : Télécharger le binaire (toutes plateformes)

Récupérez un binaire précompilé sur 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

Il va directement dans le chat avec son provider intégré déjà actif. Lancez opencrabs --onboard quand vous voulez l’assistant de configuration.

Windows est une plateforme native (v0.5.3) : gestion du shell consciente de la plateforme, lecture BOM/UTF-16 et fallbacks tilde/cwd intégrés, et la CI compile Windows à chaque PR (#627).

Vérifiez votre téléchargement (optionnel) : chaque release publie un fichier SHA256SUMS à côté des tarballs.

Permissions terminal requises. OpenCrabs lit/écrit des fichiers brain, la config et des fichiers de projet. Votre app de terminal doit avoir accès au système de fichiers, sinon l’OS bloque les opérations.

OS	Quoi faire
macOS	Réglages Système → Confidentialité et sécurité → Accès complet au disque → activez votre app de terminal (Alacritty, iTerm2, Terminal, etc.). Si elle n’est pas listée, cliquez sur “+” et ajoutez-la depuis /Applications/. Sans cela, macOS répète « voudrait accéder aux données d’autres apps ».
Windows	Lancez votre terminal (Windows Terminal, PowerShell, cmd) en tant qu’administrateur au premier lancement, ou donnez au terminal l’accès en écriture à %USERPROFILE%\.opencrabs\ et à vos répertoires de projet. Windows Defender peut aussi demander, cliquez sur « Autoriser ».
Linux	Assurez-vous que votre utilisateur possède ~/.opencrabs/ et vos répertoires de projet. Sur les systèmes SELinux/AppArmor, le processus du terminal a besoin d’un accès lecture/écriture à ces chemins. Les terminaux Flatpak/Snap peuvent nécessiter --filesystem=home ou une permission équivalente.

Le /rebuild fonctionne même avec des binaires précompilés, il clone automatiquement le source vers ~/.opencrabs/source/ à la première utilisation, puis compile et fait un hot-restart.

Option 3 : Compiler depuis le source

Nécessaire pour /rebuild, ajouter des outils personnalisés ou modifier l’agent.

Configuration rapide (recommandé)

Le script de configuration détecte automatiquement votre plateforme (macOS, Debian/Ubuntu, Fedora/RHEL, Arch) et installe toutes les dépendances de build + Rust :

# Installer toutes les dépendances
curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/src/scripts/setup.sh | bash

# Cloner et compiler
git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

Configuration manuelle

Si vous préférez installer les dépendances vous-même :

• Rust stable: Installez Rust. La toolchain stable fonctionne depuis la v0.2.85
• Une clé API d’au moins un provider supporté
• SQLite (intégré via 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 utilise keys.toml au lieu de .env pour les clés API. L’assistant d’onboarding vous aidera à le configurer, ou éditez ~/.opencrabs/keys.toml directement.

Option 4 : Docker

Lancez OpenCrabs dans un conteneur isolé. La compilation prend ~15 min (Rust release + LTO).

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

La config, le workspace et la DB de mémoire persistent dans un volume Docker à travers les redémarrages. Les clés API dans keys.toml sont montées dans le conteneur à l’exécution, jamais cuites dans l’image.

Démarrage automatique au boot

Gardez OpenCrabs en marche comme daemon d’arrière-plan qui démarre avec votre système.

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.

Vérifiez l’état : 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

Mettez à jour le chemin dans ProgramArguments pour correspondre à votre emplacement d’installation.

Windows (Task Scheduler)

1. Win + R → taskschd.msc
2. Créer une tâche de base → Nom : OpenCrabs
3. Déclencheur : Quand j’ouvre une session
4. Action : Démarrer un programme → C:\Users\<vous>\.cargo\bin\opencrabs.exe, Arguments : daemon
5. Dans Properties > Settings, cochez If the task fails, restart every 1 minute

Ou via 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

Mettre à jour

• Utilisateurs Homebrew : brew upgrade opencrabs (si vous tapez /evolve sur une installation Homebrew, il délègue à Homebrew, le binaire reste géré par brew, et l’ancien tap est retiré au profit des autobumps de homebrew-core)
• Utilisateurs du binaire : Tapez /evolve dans le TUI pour télécharger la dernière release
• Utilisateurs du source : git pull && cargo build --release, ou tapez /rebuild dans le TUI
• Utilisateurs Docker : docker compose pull && docker compose up -d