Oji Assistant

A modern, cross-platform AI chat application built with React and Chakra UI. Oji provides an intuitive interface for AI conversations with support for both streaming and non-streaming responses.

• Oji Assistant
  • 🚀 Installation
    • 🖥️ Desktop App (Electron)
    • 🌐 Web App
  • 🔨 Build from Source
    • Prerequisites
    • Development Setup
      • 1. Clone the repository
      • 2. Install dependencies
      • 3. Development Mode
    • Production Builds
      • Desktop Apps
      • Web App
      • Docker Deployment
  • 🔧 Configuration
    • AI Service Setup
    • Environment Variables
    • Environment Variables (Web Version)
  • 🚀 Deployment
    • Web Deployment
    • Desktop Distribution

🚀 Installation

🖥️ Desktop App (Electron)

Oji is available as native desktop applications for all major platforms:

• macOS: Native app with system integration (Intel and Apple Silicon)
• Windows: Native app with installer
• Linux: AppImage, DEB, and RPM packages

📖 For detailed installation instructions, see: Desktop Installation Guide | 桌面安装指南

🌐 Web App

Access Oji directly in your browser or deploy your own instance:

• Online Version: https://apepkuss.github.io/Oji-Assistant
• Self-Hosted: Download and deploy the web version on your own server
• PWA Support: Can be installed as a desktop app from your browser
• Mobile Friendly: Responsive design for mobile devices

📖 For detailed web installation and deployment instructions, see: Web Installation Guide | 网页版安装指南

🔨 Build from Source

Prerequisites

• Node.js 18+
• npm or yarn

Development Setup

1. Clone the repository

git clone https://github.com/apepkuss/Oji-Assistant.git
cd Oji-Assistant

2. Install dependencies

npm install

3. Development Mode

For web development:

npm run dev

The development server will start at http://localhost:5173

Production Builds

Desktop Apps

# Build for all platforms
npm run electron:dist

# Build for specific platforms
npm run build:mac      # macOS
npm run build:win      # Windows
npm run build:linux    # Linux

Web App

# Build web version
npm run build:web

# Preview web build locally
npm run preview:web

The web app will be available at http://localhost:4173/

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Access at http://localhost:8080

🔧 Configuration

AI Service Setup

1. Configure your AI service endpoint in the app settings
2. No default endpoint - requires manual configuration
3. Supports OpenAI-compatible APIs

Environment Variables

# Default AI service URL (for web builds)
VITE_DEFAULT_AI_SERVICE_BASE_URL=http://{host}:{port}/v1

# App version
VITE_APP_VERSION=1.0.0

These environment variables can be set during build time:

# Build with custom AI service URL
VITE_DEFAULT_AI_SERVICE_BASE_URL=http://{host}:{port}/v1 npm run build:web

# Or create a .env file
echo "VITE_DEFAULT_AI_SERVICE_BASE_URL=http://{host}:{port}/v1" > .env
npm run build:web

Environment Variables (Web Version)

For the web version, you can set default AI service configuration using runtime environment variables:

# Development with custom settings
AI_BASE_URL=http://your-ai-server:9068/v1 AI_API_KEY=your-api-key npm run dev

# Build with custom settings
AI_BASE_URL=http://your-ai-server:9068/v1 AI_API_KEY=your-api-key npm run build

# Preview with custom settings
AI_BASE_URL=http://your-ai-server:9068/v1 AI_API_KEY=your-api-key npm run preview

Available environment variables:

• AI_BASE_URL - Set the default AI service base URL
• AI_API_KEY - Set the default API key

These runtime environment variables will override any build-time defaults and provide the initial values in the Server Settings page.

For detailed usage instructions, see ENVIRONMENT_VARIABLES.md | 环境变量配置说明.

🚀 Deployment

Web Deployment

See WEB_DEPLOYMENT.md | 网页部署指南 for detailed deployment instructions including:

• GitHub Pages automatic deployment
• Docker deployment
• Static file server deployment
• PWA installation
• CORS configuration

Desktop Distribution

See ELECTRON_SETUP.md | Electron 配置指南 for detailed Electron app setup and distribution.

GitHub Actions automatically builds and releases desktop apps when you create a version tag:

git tag v1.0.0
git push origin v1.0.0

For production preview:

npm run preview:web

The application will be available at http://localhost:5173 (dev) or http://localhost:4173 (preview).