Codakey
Play
← Back to opencrabs

How to Deploy & Use opencrabs

Deployment and Usage Guide for OpenCrabs

This guide provides comprehensive instructions for deploying and using OpenCrabs, the self-hosted, autonomous AI agent.

1. Prerequisites

Before you begin, ensure you have the following installed and configured:

  • Rust Toolchain: OpenCrabs is built with Rust. You need rustup to manage Rust versions. 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    Ensure you have the latest stable Rust toolchain.
  • Git: For cloning the repository. 
    # Debian/Ubuntu
sudo apt-get install git
# macOS (with Homebrew)
brew install git
  • OpenSSL Development Libraries: Required for some Rust crates. 
    # Debian/Ubuntu
sudo apt-get install libssl-dev
# macOS (with Homebrew)
brew install openssl
  • SQLite Development Libraries: Required for the internal database. 
    # Debian/Ubuntu
sudo apt-get install libsqlite3-dev
# macOS (with Homebrew)
brew install sqlite
  • Docker (Optional): For running OpenCrabs in a containerized environment. Install Docker
  • AI Provider Accounts & API Keys:
    • OpenAI: For GPT models.
    • Anthropic: For Claude models.
    • OpenRouter: For access to 400+ models.
    • MiniMax: For MiniMax models.
    • Groq: For Whisper (STT) and other models if used.
    • Telegram: If using the Telegram bot, you'll need a bot token from @BotFather.
    • Discord: If using the Discord bot, you'll need a bot token and application ID.
    • Slack: If using the Slack bot, you'll need a bot token and app token (Socket Mode required) from api.slack.com/apps.
    • Trello: If using the Trello tool, you'll need API credentials.

2. Installation

  1. Clone the repository:

    git clone https://github.com/adolfousier/opencrabs.git
cd opencrabs

  2. Build the project:

    cargo build --release

    This will compile the single binary and place it in target/release/opencrabs.

3. Configuration

OpenCrabs uses a keys.toml file for API keys and environment variables for other settings. It also creates a ~/.opencrabs directory for configuration, memory, and history.

API Keys (keys.toml)

Create a keys.toml file in the root of the project or in ~/.opencrabs/keys.toml. Example keys.toml:

# OpenAI API Key
openai_api_key = "sk-..."

# Anthropic API Key
anthropic_api_key = "sk-ant-..."

# OpenRouter API Key
openrouter_api_key = "sk-or-..."

# MiniMax API Key
minimax_api_key = "sk-..."

# Groq API Key (for Whisper STT)
groq_api_key = "sk-..."

# Telegram Bot Token
telegram_bot_token = "YOUR_TELEGRAM_BOT_TOKEN"

# Discord Bot Token
discord_bot_token = "YOUR_DISCORD_BOT_TOKEN"
discord_application_id = "YOUR_DISCORD_APPLICATION_ID"

# Slack Bot Token (xoxb-...) and App Token (xapp-...)
slack_bot_token = "xoxb-..."
slack_app_token = "xapp-..."

# Trello API Key and Token (obtained via trello_connect tool or manually)
# trello_api_key = "YOUR_TRELLO_API_KEY"
# trello_api_token = "YOUR_TRELLO_API_TOKEN"

Environment Variables

While keys.toml is preferred for API keys, some settings can be controlled via environment variables. Refer to the src/config.rs for a full list.

Configuration Directory

OpenCrabs uses ~/.opencrabs as its home directory. This is where:

  • history.txt (input history) is stored.
  • memory/YYYY-MM-DD.md (daily logs) are stored.
  • whatsapp/session.db (WhatsApp session data) is stored.
  • keys.toml can be placed.

Local LLMs

OpenCrabs supports local LLMs via any OpenAI-compatible endpoint (e.g., Ollama, LM Studio, LocalAI). To use a local LLM:

  1. Start your local LLM server (e.g., ollama serve or LM Studio).
  2. Configure the api_base URL in the OpenCrabs UI when selecting a provider, or specify it in a configuration file if available (not explicitly detailed in README, but implied by "any OpenAI-compatible API").

4. Build & Run

Development Build

To build for development with debug information:

cargo build

To run the development version:

cargo run

Production Build

To build an optimized, smaller binary for production:

cargo build --release

To run the production version:

./target/release/opencrabs

Onboarding Wizard

The first time you run OpenCrabs, it will launch an interactive onboarding wizard to help set up initial configurations, including API keys and channel integrations.

Usage

Once running, OpenCrabs presents a TUI (Terminal User Interface).

  • Type your prompts in the input area.
  • Use keyboard shortcuts (see below) to navigate and interact.
  • Attach images by pasting file paths or URLs into the input.
  • Attach PDF files by path.
  • Interact with integrated channels (Telegram, WhatsApp, Discord, Slack) from the shared session.

Keyboard Shortcuts

  • Ctrl+C / Esc: Exit the application.
  • Ctrl+S: Save current session/state (if applicable).
  • Ctrl+Backspace / Alt+Backspace: Delete the word before the cursor.
  • Arrow Keys: Navigate input history and UI elements.
  • Tab: Switch between panes/modes.
  • Enter: Submit input.

5. Deployment

OpenCrabs is a single Rust binary, making it highly portable.

Local Machine (Self-Hosted)

The simplest deployment is to run the binary directly on your machine or a dedicated server.

  1. Build the release binary: 
    cargo build --release
  2. Copy the binary and keys.toml: 
    cp target/release/opencrabs /usr/local/bin/opencrabs
# Place keys.toml in ~/.opencrabs/ or the same directory as the binary
mkdir -p ~/.opencrabs
cp keys.toml ~/.opencrabs/keys.toml
  3. Run: 
    opencrabs
    For persistent operation, consider using a process manager like systemd or supervisor.

Docker

OpenCrabs can be containerized for easier deployment and isolation. A Dockerfile is implied by the Docker badge.

  1. Build the Docker image:

    docker build -t opencrabs .

  2. Run the Docker container: You'll need to mount the ~/.opencrabs directory for persistent data and pass API keys as environment variables or mount keys.toml.

    docker run -it --name opencrabs_agent \
    -v ~/.opencrabs:/app/.opencrabs \
    -e OPENAI_API_KEY="sk-..." \
    -e TELEGRAM_BOT_TOKEN="YOUR_TOKEN" \
    # ... add other API keys as needed ...
    opencrabs

    Note: The -v ~/.opencrabs:/app/.opencrabs maps your local OpenCrabs data directory to the container's internal data directory, ensuring persistence across container restarts. Adjust /app/.opencrabs if the container's working directory or expected config path differs.

Cloud Platforms (e.g., AWS EC2, Google Cloud Compute Engine, DigitalOcean Droplets)

Deploying to a cloud VM is similar to local machine deployment.

  1. Provision a VM: Choose a Linux-based VM instance.

  2. SSH into the VM.

  3. Install Prerequisites: Install Rust, Git, OpenSSL libs, SQLite libs.

  4. Clone and Build: Follow the "Installation" and "Production Build" steps.

  5. Configure keys.toml: Place it in ~/.opencrabs/keys.toml.

  6. Run with a Process Manager: Use systemd to ensure OpenCrabs runs continuously and restarts on failure or reboot.

    Example systemd service file (/etc/systemd/system/opencrabs.service):

    [Unit]
Description=OpenCrabs Autonomous AI Agent
After=network.target

[Service]
User=your_username
WorkingDirectory=/home/your_username/opencrabs
ExecStart=/home/your_username/opencrabs/target/release/opencrabs
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
Environment="RUST_LOG=info" # Optional: for logging level

[Install]
WantedBy=multi-user.target

    Reload systemd and enable the service:

    sudo systemctl daemon-reload
sudo systemctl enable opencrabs
sudo systemctl start opencrabs
sudo systemctl status opencrabs

6. Troubleshooting

  • error: linker cc not found:
    • Solution: Install a C compiler. 
      # Debian/Ubuntu
sudo apt-get install build-essential
# macOS (with Homebrew)
xcode-select --install
  • error: failed to run custom build command for openssl-sys v...``:
    • Solution: Ensure OpenSSL development libraries are installed. 
      # Debian/Ubuntu
sudo apt-get install libssl-dev
# macOS (with Homebrew)
brew install openssl && export PKG_CONFIG_PATH="/usr/local/opt/openssl/lib/pkgconfig"
  • error: failed to run custom build command for sqlite3-sys v...``:
    • Solution: Ensure SQLite development libraries are installed. 
      # Debian/Ubuntu
sudo apt-get install libsqlite3-dev
# macOS (with Homebrew)
brew install sqlite
  • AI Provider API Key Issues:
    • Symptom: "Invalid API Key" or similar errors from the AI model.
    • Solution: Double-check your keys.toml for typos. Ensure the key is valid for the selected provider and has the necessary permissions.
  • Channel Integration Failures (Telegram, WhatsApp, Discord, Slack):
    • Symptom: Bot not responding, "Failed to connect" messages.
    • Solution:
      • Verify bot tokens and application IDs in keys.toml.
      • Ensure the bot has necessary permissions in its respective platform.
      • For WhatsApp, ensure the QR code pairing was successful and the session file (~/.opencrabs/whatsapp/session.db) is persistent.
      • For Slack, confirm Socket Mode is enabled for your app.
      • Check RUST_LOG=debug output for specific error messages.
  • Local LLM Connection Issues:
    • Symptom: "Failed to connect to local LLM" or "API endpoint unreachable."
    • Solution:
      • Ensure your local LLM server (Ollama, LM Studio, etc.) is running and accessible on the specified port.
      • Verify the api_base URL configured in OpenCrabs matches your local server's address.
  • TUI Display Issues:
    • Symptom: Garbled text, incorrect layout in the terminal.
    • Solution: Ensure your terminal emulator supports Unicode and true color. Try resizing the terminal window.
  • Debug Logging:
    • Solution: Run OpenCrabs with the RUST_LOG environment variable for detailed output: 
      RUST_LOG=debug ./target/release/opencrabs
      This will print detailed logs to stderr, which can help diagnose issues.
← Project overviewView alternatives to opencrabs →