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.

Opção 1: Homebrew (recomendado em macOS e 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.

Corre opencrabs depois de instalar. Vai direto para o chat com o provider incorporado já ativo, por isso o crab cumprimenta-te e podes começar a falar. Corre opencrabs --onboard quando quiseres o assistente de configuração.

Opção 2: Descarregar Binário (todas as plataformas)

Vai buscar um binário pré-compilado ao 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

Vai direto para o chat com o provider incorporado já ativo. Corre opencrabs --onboard quando quiseres o assistente de configuração.

O Windows é uma plataforma de primeira classe (v0.5.3): shell handling consciente da plataforma, leitura BOM/UTF-16 e fallbacks de tilde/cwd incluídos, e a CI compila Windows em cada PR (#627).

Verifica o download (opcional): cada release publica um ficheiro SHA256SUMS junto com os tarballs.

Permissões de terminal necessárias. O OpenCrabs lê e escreve ficheiros brain, config e ficheiros de projeto. A tua app de terminal precisa de acesso ao sistema de ficheiros ou o SO bloqueia as operações.

SO	O que fazer
macOS	Definições do Sistema → Privacidade e Segurança → Acesso Total ao Disco → ativa a tua app de terminal (Alacritty, iTerm2, Terminal, etc.). Se não estiver listada, clica em “+” e adiciona-a a partir de /Applications/. Sem isto, o macOS pergunta repetidamente “quer aceder a dados de outras apps”.
Windows	Corre o terminal (Windows Terminal, PowerShell, cmd) como Administrador na primeira execução, ou dá ao terminal acesso de escrita a %USERPROFILE%\.opencrabs\ e aos teus diretórios de projeto. O Windows Defender também pode perguntar, clica em “Permitir”.
Linux	Garante que o teu utilizador é dono de ~/.opencrabs/ e dos diretórios de projeto. Em sistemas SELinux/AppArmor, o processo do terminal precisa de acesso de leitura/escrita a esses caminhos. Terminais Flatpak/Snap podem precisar de --filesystem=home ou permissão equivalente.

O /rebuild funciona mesmo com binários pré-compilados: clona automaticamente o source para ~/.opencrabs/source/ na primeira utilização, depois compila e faz hot-restart.

Opção 3: Compilar a partir do Source

Necessário para /rebuild, adicionar ferramentas personalizadas ou modificar o agente.

Configuração rápida (recomendado)

O script de configuração deteta automaticamente a tua plataforma (macOS, Debian/Ubuntu, Fedora/RHEL, Arch) e instala todas as dependências de build + Rust:

# Instalar todas as dependências
curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/src/scripts/setup.sh | bash

# Clonar e compilar
git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

Configuração manual

Se preferires instalar as dependências tu mesmo:

• Rust stable: Instala o Rust. A toolchain stable funciona desde a v0.2.85
• Uma chave de API de pelo menos um provider suportado
• SQLite (incluído 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

O OpenCrabs usa keys.toml em vez de .env para chaves de API. O assistente de onboarding ajuda-te a configurar, ou edita ~/.opencrabs/keys.toml diretamente.

Opção 4: Docker

Corre o OpenCrabs num contentor isolado. A compilação demora ~15min (Rust release + LTO).

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

A config, o workspace e a DB de memória persistem num volume Docker entre reinícios. As chaves de API em keys.toml são montadas no contentor em runtime, nunca vão parar dentro da imagem.

Arranque Automático no Boot

Mantém o OpenCrabs a correr como daemon de fundo que arranca com o teu 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.

Verifica o 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

Atualiza o caminho em ProgramArguments para corresponder ao local de instalação.

Windows (Task Scheduler)

1. Win + R → taskschd.msc
2. Criar Tarefa Básica → Nome: OpenCrabs
3. Gatilho: Quando inicio sessão
4. Ação: Iniciar um programa → C:\Users\<tu>\.cargo\bin\opencrabs.exe, Argumentos: daemon
5. Em Properties > Settings, marca 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

Atualizar

• Utilizadores de Homebrew: brew upgrade opencrabs (se escreveres /evolve numa instalação Homebrew, delega para o Homebrew, o binário fica gerido pelo brew, e o tap antigo foi reformado em favor dos autobumps do homebrew-core)
• Utilizadores de binário: Escreve /evolve no TUI para descarregar a última release
• Utilizadores de source: git pull && cargo build --release, ou escreve /rebuild no TUI
• Utilizadores de Docker: docker compose pull && docker compose up -d