Documentation

Your LLMs, Your Control

• API Key Privacy: Your API keys are stored locally and encrypted, never transmitted to our servers.
• Local Storage Only: All conversations and settings stay on your device using IndexedDB and LocalStorage.
• No Account Required: Start chatting immediately without creating accounts or sharing personal information.

LLM Integration & Model Configuration

• Full Parameter Control: Customize temperature, top-p, frequency penalty, and more.
• Multi-Model Support: Switch between OpenAI, Anthropic, and Google models with ease.
• System Prompts: Set custom instructions for more targeted responses.

Chat Interface & Messaging

• Dynamic chat UI with a comprehensive chat panel, message list, and individual message components.
• Real-time response streaming to see responses appear word-by-word.
• Responsive UI that works seamlessly on desktop and mobile devices.

Organization & Customization

• Message Pinning: Highlight important information and questions.
• Folder Organization: Keep conversations structured by project, topic, or purpose.
• Theme Options: Light, dark, and system theme support.
• Accessibility Focus: Designed with accessibility in mind.

Local Data Persistence

• All data (chats, settings, folders, etc.) is persisted in the browser using IndexedDB and LocalStorage.
• Export and import functionality to back up and restore your conversation history.
• Robust storage management ensures data consistency and offline access.

Modern Design & Performance

• Modern, responsive design built with Tailwind CSS and shadcn/ui components.
• Optimized performance with efficient state management using custom React hooks.
• Thoughtful UX design for intuitive interaction.

Method 1: Using the Hosted Version

The easiest way to get started is to use the hosted version at https://justbyok.app.

Method 2: Running Locally

1. Clone the repository:

   git clone https://github.com/danielhafezi/JustBYOK.git
   cd JustBYOK

2. Install dependencies:

   npm install
   # or
   yarn install

3. Run the development server:

   npm run dev
   # or
   yarn dev

   Open http://localhost:3000 in your browser to use the application.

OpenAI API Key

• For GPT-4o, GPT-4o mini, and GPT-4.5 Preview
• Go to OpenAI API
• Create a new API key
• Copy the key

Anthropic API Key

• For Claude Sonnet 3.7 models
• Go to Anthropic Console
• Sign up or sign in
• Navigate to API Keys and create a new key
• Copy the key

Google Gemini API Key

• For Gemini Flash 2
• Go to Google AI Studio
• Create a new API key
• Copy the key

Adding Keys to JustBYOK

1. Click on Settings
2. Navigate to the API Keys section
3. Paste your keys in the appropriate fields

Chat Interface

The JustBYOK interface consists of several key components:

• Sidebar: Access chats, folders, and settings
• Chat Window: View and send messages
• Model Selector: Choose which LLM to use
• Parameter Controls: Adjust model settings
• Message Input: Type your messages here

Model Selection

1. Click the model dropdown in the top bar of the chat window
2. Choose from available models:
   • OpenAI: GPT-4o, GPT-4o mini, GPT-4.5 Preview
   • Anthropic: Claude Sonnet 3.7, Claude Sonnet 3.7 (Reasoning)
   • Google: Gemini Flash 2
3. The chat will now use your selected model for all new messages

Conversation Management

JustBYOK provides several tools for organizing your conversations:

• New Chat: Create a new conversation
• Rename Chat: Click on the chat title to rename it
• Delete Chat: Remove unwanted conversations
• Star Favorites: Mark important chats with the star icon
• Move to Folder: Organize chats in folders
• Export/Import: Back up and restore your conversation history

User Interface

• Theme: Light, Dark, or System
• Font Size: Small, Medium, or Large
• Message Bubble Style: Modern or Classic

Behavior

• Enter to Send: Enable/disable sending messages with Enter key
• Show Timestamps: Display message timestamps
• Auto-save Drafts: Automatically save unsent messages
• Auto-generate Titles: Create chat titles based on content

Model Settings

Customize model parameters using the model settings dialog:

• Temperature (0.0-1.0): Controls randomness (higher = more creative, lower = more deterministic)
• Top P (0.0-1.0): Nucleus sampling parameter for response diversity
• Frequency Penalty (0.0-2.0): Reduces repetition of frequent tokens
• Presence Penalty (0.0-2.0): Reduces repetition of topics
• Maximum Tokens: Limit response length
• Context Limit: Control how much conversation history to include
• Reasoning Effort (Anthropic only): Adjust the model's reasoning depth
• System Message: Defines the AI assistant's behavior and context

Storage

Data is stored locally in the browser to ensure quick retrieval and offline capability:

• Chat History: Stored in IndexedDB for efficient access and persistence
• User Settings: Preferences and configurations saved in LocalStorage
• Folders & Organization: Structure information stored locally
• Export/Import: Tools to backup and restore your data

System Prompts

System prompts help define the LLM's behavior:

1. Go to Settings > Model Settings
2. Find the System Prompt section
3. Enter instructions for the AI (e.g., "You are a helpful programming assistant who writes clean, commented code")
4. Save your changes

System prompts can define:

• The model's persona or role
• Formatting preferences
• Response style and tone
• Task-specific instructions

Pinning & Organizing

To keep your chats organized:

• Pin Messages: Click the pin icon on any message to highlight it
• Star Chats: Mark favorite conversations for easy access
• Search: Use the search function to find specific conversations
• Sort: Arrange chats by date, name, or model

Folder Management

Create a folder system to organize your chats:

1. Click "New Folder" in the sidebar
2. Name your folder
3. Drag and drop chats into folders, or use the "Move to Folder" option
4. Rename, delete, or create subfolders as needed

Local Storage & Backup

JustBYOK uses two types of browser storage:

• IndexedDB: Stores chat history, messages, and folders
• LocalStorage: Stores settings and API keys

For backup:

1. Go to Settings > Data Management
2. Use Export to save your data
3. Use Import to restore from a backup

OpenAI Models

• GPT-4o: OpenAI's most capable multimodal model
• GPT-4o mini: A smaller, faster version of GPT-4o
• GPT-4.5 Preview: The latest cutting-edge model from OpenAI

Anthropic Models

• Claude Sonnet 3.7: Anthropic's flagship conversational AI
• Claude Sonnet 3.7 (Reasoning): Enhanced version with stronger reasoning capabilities

Google Models

• Gemini Flash 2: Google's fast, efficient multimodal model

Client-Side Architecture

1. Chat Database: Uses IndexedDB for persistent storage of chats and messages
2. API Key Management: Secure local storage of API keys
3. UI Layer: React components for the user interface
4. API Integration: Direct browser-to-API communication
5. Settings Management: LocalStorage for user preferences

Frontend

Built with Next.js and React, utilizing a custom UI component library.

• React components for UI elements and interactive features
• Custom hooks for state management and business logic
• Responsive design principles throughout the application

Backend

API routes under app/api/chat/ and app/api/simplechat/ manage chat data and interface with LLM backends.

• Next.js API routes for handling requests
• Integration with various LLM providers
• Request and response formatting for different chat models

Data Persistence

LocalStorage and IndexedDB are used to store user settings, chat history, and other configurations.

• IndexedDB for storing larger datasets like chat history
• LocalStorage for user preferences and settings
• Efficient data structures for quick retrieval and updates

State Management

Custom hooks encapsulate state logic and UI interactions.

• Modular state management with custom React hooks
• Consistent state updates across components
• Optimized rendering for better performance

API Connection Issues

If you're having trouble connecting to an LLM provider:

1. Verify your API key is entered correctly
2. Check that you have sufficient credits/quota with the provider
3. Ensure you're not behind a restrictive firewall
4. Try a different browser or disable browser extensions

Local Storage Issues

If you're experiencing data persistence problems:

1. Make sure cookies and local storage are enabled in your browser
2. Check that you're not in private/incognito mode
3. Verify you have sufficient disk space
4. Try exporting your data as a backup

Performance Issues

For better performance:

1. Clear old conversations you don't need
2. Use shorter context windows in the settings
3. Try models with lower computational requirements
4. Reduce the maximum token limit for responses