Skip to content

Installation Setup

Jump to bottom
Mo Abualruz edited this page Dec 24, 2025 · 5 revisions

Installation & Setup

Get RiceCoder installed and configured for your system.

Overview

This guide walks you through installing RiceCoder on your system and configuring it for your first use. It covers system requirements, installation methods for different platforms, post-installation setup, and troubleshooting common installation issues.

System Requirements

  • OS: Linux, macOS, or Windows
  • Rust: 1.75+ (for building from source)
  • Git: For version control integration
  • Terminal: Any modern terminal (bash, zsh, fish, PowerShell)

Installation Methods

Method 1: Cargo (Recommended)

Install from crates.io - the easiest and most portable method:

# Install ricecoder
cargo install ricecoder

# Verify installation
rice --version

Updating to the latest version:

# Update to the latest version
cargo install --force ricecoder

# Or use the shorter form
cargo install -f ricecoder

Uninstalling:

# Remove ricecoder
cargo uninstall ricecoder

Advantages:

  • ✅ Works on all platforms (Linux, macOS, Windows)
  • ✅ Easy to update
  • ✅ No system dependencies
  • ✅ Automatic PATH setup

Requirements:

Platforms: Linux (x86_64, ARM64), macOS (Intel, Apple Silicon), Windows (x86_64, ARM64)

Method 2: Curl Script (Quick Setup)

Build and install from source with a single command:

# Install
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash

# With custom prefix
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash -s -- --prefix /usr/local

# Debug build
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash -s -- --debug

# Verify
rice --version

What it does:

  1. Detects your OS and architecture
  2. Downloads the installation script
  3. Checks prerequisites (Rust, Cargo, Git)
  4. Updates Rust toolchain
  5. Builds from source
  6. Installs binaries to specified prefix
  7. Verifies installation

Advantages:

  • ✅ Single command
  • ✅ Automatic platform detection
  • ✅ Prerequisite checking
  • ✅ Automatic Rust update
  • ✅ Customizable installation prefix
  • ✅ Installation verification

Requirements:

  • curl
  • bash or sh
  • Rust 1.75+ (will be installed/updated automatically)

Platforms: Linux (x86_64, ARM64), macOS (Intel, Apple Silicon)

Troubleshooting:

  • If script fails, try: bash -c "$(curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install)"
  • For Windows, use PowerShell script or Cargo instead

Method 3: npm (Node.js Developers)

Install via npm registry:

# Install globally
npm install -g ricecoder

# Verify
rice --version

# Update
npm install -g ricecoder@latest

# Uninstall
npm uninstall -g ricecoder

What it does:

  1. Downloads pre-built binary for your platform
  2. Installs to npm global directory
  3. Creates rice command in PATH

Advantages:

  • ✅ Familiar npm workflow
  • ✅ Easy version management
  • ✅ Works with Node.js projects
  • ✅ Cross-platform

Requirements:

Platforms: Linux, macOS, Windows

Method 4: Homebrew (macOS)

Install via Homebrew package manager:

# Install
brew install ricecoder

# Verify
rice --version

# Update
brew upgrade ricecoder

# Uninstall
brew uninstall ricecoder

Advantages:

  • ✅ Native macOS integration
  • ✅ Easy updates
  • ✅ System package manager
  • ✅ Automatic dependency management

Requirements:

Platforms: macOS only

Method 5: Docker

Run RiceCoder in a Docker container for isolated, reproducible environments:

# Pull the image
docker pull moabualruz/ricecoder:latest

# Run RiceCoder
docker run --rm moabualruz/ricecoder:latest --version

# Run with volume mounting for workspace access
docker run -it -v $(pwd):/workspace moabualruz/ricecoder:latest chat

# Run with environment variables
docker run -it \
  -e OPENAI_API_KEY="your-key" \
  -v $(pwd):/workspace \
  moabualruz/ricecoder:latest chat

Advantages:

  • ✅ Isolated environment
  • ✅ No system dependencies
  • ✅ Consistent across platforms
  • ✅ Easy cleanup
  • ✅ Works on any platform with Docker

Requirements:

Platforms: Any platform with Docker (Linux, macOS, Windows)

Image Tags:

  • latest - Latest stable release
  • v0.1.6 - Specific version
  • dev - Development version (if available)

See Also: Docker Setup Guide - Comprehensive Docker documentation

Method 6: Build from Source

Clone and build locally for development or customization.

Using Installation Scripts (Recommended)

Automated build and installation with prerequisite checking:

Linux/macOS:

# Clone the repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Make script executable
chmod +x scripts/install.sh

# Run installation script
./scripts/install.sh

# Verify installation
rice --version

Installation Script Options:

# Install to custom prefix
./scripts/install.sh --prefix /usr/local

# Debug build (faster compilation)
./scripts/install.sh --debug

# Verbose output
./scripts/install.sh --verbose

# Show help
./scripts/install.sh --help

Windows (PowerShell):

# Clone the repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Run installation script
.\scripts\install.ps1

# Verify installation
rice --version

Installation Script Options:

# Install to custom prefix
.\scripts\install.ps1 -Prefix "C:\Program Files\ricecoder"

# Debug build
.\scripts\install.ps1 -Debug

# Verbose output
.\scripts\install.ps1 -Verbose

# Show help
.\scripts\install.ps1 -Help

Windows (CMD):

# Clone the repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Run installation script
scripts\install.bat

# Verify installation
rice --version

Installation Script Options:

# Install to custom prefix
scripts\install.bat --prefix "C:\Program Files\ricecoder"

# Debug build
scripts\install.bat --debug

# Verbose output
scripts\install.bat --verbose

# Show help
scripts\install.bat --help

Manual Build and Install

For advanced users or custom builds:

# Clone the repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Build and install
cargo install --path projects/ricecoder

# Verify installation
rice --version

Advantages:

  • ✅ Latest development version
  • ✅ Full source access
  • ✅ Customizable build
  • ✅ Contribute to development
  • ✅ Automatic prerequisite checking (with scripts)
  • ✅ Automatic Rust toolchain update (with scripts)

Requirements:

  • Rust 1.75+ (Install Rust)
  • Git
  • C compiler (gcc, clang, or MSVC)

Platforms: Linux, macOS, Windows

Development Setup:

# Clone with submodules
git clone --recursive https://github.com/moabualruz/ricecoder.git

# Build in debug mode (faster compilation)
cargo build

# Build in release mode (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- chat

Installation Script Features:

The installation scripts provide:

  • ✅ Automatic OS and architecture detection
  • ✅ Prerequisite verification (Rust, Cargo, Git)
  • ✅ Automatic Rust toolchain update
  • ✅ Configurable build mode (release/debug)
  • ✅ Automatic binary installation
  • ✅ Configuration file installation
  • ✅ Documentation installation
  • ✅ Installation verification
  • ✅ PATH configuration guidance
  • ✅ Comprehensive error handling

See Also: Installation Guide - Comprehensive build and installation documentation

Platform Support Matrix

Platform Arch Cargo Curl npm Homebrew Docker Source
Linux x86_64 ✅ ✅ ✅ ❌ ✅ ✅
Linux ARM64 ✅ ✅ ✅ ❌ ✅ ✅
macOS Intel ✅ ✅ ✅ ✅ ✅ ✅
macOS Apple Silicon ✅ ✅ ✅ ✅ ✅ ✅
Windows x86_64 ✅ ❌ ✅ ❌ ✅ ✅
Windows ARM64 ✅ ❌ ✅ ❌ ✅ ✅

Legend: ✅ Supported | ❌ Not available

Choosing an Installation Method

Use Cargo if:

  • You have Rust installed
  • You want the easiest cross-platform method
  • You want automatic updates

Use Curl if:

  • You're on Linux or macOS
  • You want a quick one-line install
  • You don't have Rust installed

Use npm if:

  • You're a Node.js developer
  • You want npm-style version management
  • You're on Windows

Use Homebrew if:

  • You're on macOS
  • You prefer system package managers
  • You want native integration

Use Docker if:

  • You want an isolated environment
  • You need consistent setup across machines
  • You don't want to install dependencies

Use Source if:

  • You're contributing to development
  • You need the latest development version
  • You want to customize the build

Post-Installation Setup

1. Verify Installation

After installation, verify RiceCoder is working:

# Check version
rice --version

# Show help
rice --help

# Check system information
rice info --system

2. Initialize RiceCoder

Initialize your first project:

rice init

This creates:

  • ~/.ricecoder/ - Global configuration directory
  • .agent/ - Project-specific configuration (in current directory)
  • .ricecoder/config.yaml - Project configuration file

What gets created:

  • Global config: ~/.ricecoder/config.yaml
  • Project config: .agent/config.yaml
  • Steering files: .ai/steering/
  • Hooks: .ai/hooks/

3. Configure Your AI Provider

Choose one of the following providers:

Option A: OpenAI (Recommended)

# Get your API key from https://platform.openai.com/api-keys
export OPENAI_API_KEY="your-api-key"

# Configure RiceCoder
rice config set provider openai
rice config set model gpt-4

# Verify configuration
rice config show

Supported Models:

  • gpt-4 - Most capable (recommended)
  • gpt-4-turbo - Faster, cheaper
  • gpt-3.5-turbo - Budget option

Pricing: See OpenAI Pricing

Option B: Anthropic

# Get your API key from https://console.anthropic.com/
export ANTHROPIC_API_KEY="your-api-key"

# Configure RiceCoder
rice config set provider anthropic
rice config set model claude-3-opus

# Verify configuration
rice config show

Supported Models:

  • claude-3-opus - Most capable
  • claude-3-sonnet - Balanced
  • claude-3-haiku - Fast, budget

Pricing: See Anthropic Pricing

Option C: Local Models (Ollama)

Use local models for offline-first development:

# Install Ollama
# macOS:
brew install ollama

# Linux:
curl https://ollama.ai/install.sh | sh

# Windows:
# Download from https://ollama.ai/download

# Start Ollama service
ollama serve

# In another terminal, pull a model
ollama pull mistral

# Configure RiceCoder
rice config set provider ollama
rice config set model mistral
rice config set ollama-url http://localhost:11434

# Verify configuration
rice config show

Recommended Models:

  • mistral - Fast, good quality
  • neural-chat - Optimized for chat
  • llama2 - General purpose
  • codellama - Code generation

Advantages:

  • ✅ Offline-first (no internet required)
  • ✅ No API costs
  • ✅ Full privacy
  • ✅ Unlimited usage

See Also: Local Models Guide - Detailed Ollama setup

Option D: Other Providers

RiceCoder supports 75+ AI providers. See AI Providers Guide for complete list.

4. Verify Configuration

# Show current configuration
rice config show

# Validate configuration
rice config validate

# Test connection to provider
rice chat --test

# Show system information
rice info --system

Expected output:

✅ Configuration valid
✅ Provider connected
✅ Model available
✅ Ready to use

Environment Variables

Required

  • OPENAI_API_KEY - For OpenAI provider
  • ANTHROPIC_API_KEY - For Anthropic provider

Optional

  • RICECODER_HOME - Custom location for global config (default: ~/.ricecoder/)
  • RICECODER_LOG_LEVEL - Logging level (debug, info, warn, error)
  • RICECODER_OFFLINE - Enable offline mode (true/false)

Example

# Set environment variables
export OPENAI_API_KEY="sk-..."
export RICECODER_HOME="$HOME/.config/ricecoder"
export RICECODER_LOG_LEVEL="debug"

# Start RiceCoder
rice chat

Configuration Files

Global Configuration

Located at ~/.ricecoder/config.yaml:

# AI Provider Configuration
provider: openai
model: gpt-4
api-key: ${OPENAI_API_KEY}

# UI Configuration
theme: dracula
colors: true

# Behavior Configuration
offline-mode: false
auto-approve: false

Project Configuration

Located at .agent/config.yaml:

# Project-specific settings
project-name: my-project
language: rust

# Custom commands
commands:
  test:
    command: cargo test
    description: Run tests
  build:
    command: cargo build --release
    description: Build release binary

# Permissions
permissions:
  file-write: ask
  file-delete: deny
  shell-execute: ask

Steering Files

Located at .ai/steering/:

# Project-level rules and standards
standards:
  language: rust
  style: idiomatic
  testing: comprehensive

# AI behavior customization
ai:
  model: gpt-4
  temperature: 0.7
  max-tokens: 2000

Installation Troubleshooting

"Command not found: rice"

Problem: After installation, rice command is not found.

Solution:

  1. Restart your terminal
  2. Verify installation completed: rice --version
  3. Check PATH environment variable:
    • Linux/macOS: echo $PATH
    • Windows: echo %PATH%
  4. Verify binary location:
    • Linux/macOS: which rice
    • Windows: where rice
  5. If using custom shell (zsh, fish), reload configuration:
    • zsh: source ~/.zshrc
    • fish: source ~/.config/fish/config.fish
  6. Reinstall if needed: cargo install ricecoder

See Also: Full Troubleshooting Guide

"Permission denied"

Problem: Installation fails with permission errors.

Solution:

  1. Check file permissions:

    ls -la ~/.cargo/bin/rice

  2. Fix permissions:

    chmod +x ~/.cargo/bin/rice
chmod 755 .agent/
chmod 644 .agent/config.yaml

  3. Ensure directory is in PATH

  4. Try installing to home directory instead of system directories

See Also: Full Troubleshooting Guide

"Build failed" (Curl)

Problem: Curl installation fails during build.

Solution:

  1. Re-run installation script:

    curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash

  2. Check network connection:

    ping github.com

  3. Try alternative installation method (Cargo, Docker, npm)

  4. Check available disk space:

    df -h

  5. Try with reduced parallelism:

    curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash -s -- --debug

"API key not found"

Problem: RiceCoder can't find API key for AI provider.

Solution:

  1. Set API key as environment variable:

    # For OpenAI
export OPENAI_API_KEY="your-api-key"

# For Anthropic
export ANTHROPIC_API_KEY="your-api-key"

# Verify
echo $OPENAI_API_KEY

  2. Or set in configuration file:

    rice config set api-key "your-api-key"

  3. Verify API key is valid:

  4. Check for extra whitespace or quotes

See Also: Full Troubleshooting Guide

"Connection refused" (Ollama)

Problem: Can't connect to Ollama service.

Solution:

  1. Start Ollama service:

    ollama serve

  2. In another terminal, verify it's running:

    curl http://localhost:11434/api/tags

  3. Check Ollama is installed:

    ollama --version

  4. Check firewall isn't blocking port 11434

  5. Verify configuration:

    rice config show

See Also: Local Models Guide

"Model not found"

Problem: Ollama model is not available.

Solution:

  1. List available models:

    ollama list

  2. Pull a model:

    ollama pull mistral

  3. Verify model is installed:

    ollama list

  4. Update Ollama to latest version:

    ollama update

Recommended Models:

  • mistral - Fast, good quality
  • neural-chat - Optimized for chat
  • llama2 - General purpose
  • codellama - Code generation

See Also: Local Models Guide

"Out of memory"

Problem: RiceCoder uses too much memory or crashes.

Solution:

  1. Reduce context size:

    rice config set max-context 4000

  2. Use a smaller model:

    rice config set model gpt-3.5-turbo

  3. Use local models (Ollama) for lower memory usage:

    rice config set provider ollama

  4. Close other applications to free memory

  5. Check available memory:

    free -h  # Linux
vm_stat  # macOS

"Docker image not found"

Problem: Docker can't find RiceCoder image.

Solution:

  1. Pull the image:

    docker pull moabualruz/ricecoder:latest

  2. Verify Docker is running:

    docker ps

  3. Check internet connection:

    ping docker.io

  4. List available images:

    docker images

See Also: Docker Setup Guide

"Installation fails on Windows"

Problem: Installation fails with permission or path errors on Windows.

Solution:

  1. Run terminal as Administrator
  2. Disable antivirus temporarily during installation
  3. Check Windows PATH is not corrupted
  4. Try installing to directory without spaces
  5. If using WSL, ensure WSL2 is properly configured
  6. Restart terminal after installation

"Installation fails on macOS"

Problem: Installation fails with Homebrew or permission errors.

Solution:

  1. Verify Homebrew is installed:

    brew --version

  2. Update Homebrew:

    brew update

  3. Fix permission issues:

    sudo chown -R $(whoami) /usr/local/Cellar

  4. For M1/M2 Mac, ensure ARM64 version is used

  5. Try installing from source if binary fails

"Installation fails on Linux"

Problem: Installation fails with missing dependencies.

Solution:

  1. Install required dependencies:

    # Ubuntu/Debian
sudo apt-get install build-essential libssl-dev

# Fedora/RHEL
sudo dnf install gcc openssl-devel

# Arch
sudo pacman -S base-devel openssl

  2. Check available disk space:

    df -h

  3. Verify Linux distribution is supported (Ubuntu 18.04+, Fedora 30+, etc.)

  4. Try installing to home directory instead of system directories

Uninstallation

Remove RiceCoder

# If installed via cargo
cargo uninstall ricecoder

# If built from source
cd ricecoder
cargo uninstall --path projects/ricecoder

Remove Configuration

# Remove global configuration
rm -rf ~/.ricecoder/

# Remove project configuration
rm -rf .agent/

Next Steps

  1. Quick Start Guide - Your first project
  2. Configuration Guide - Customize RiceCoder
  3. CLI Commands - Learn all commands
  4. Spec-Driven Development - Master specs

Getting Help

See Also

Last updated: December 3, 2025

Clone this wiki locally