OR3.chat：基于 Nuxt 的开源本地优先 AI 聊天应用

Open-source, local-first AI chat that you actually own.
Use any model on OpenRouter. Keep your data on your machine. Deploy to the cloud when you're ready.

Website · Docs · Issues · Start Here

Table of Contents

• What is OR3?
• Core Features
• Quick Start
• Start Here
• Static vs Cloud — Which Do I Pick?
• Static Mode (Default)
• Cloud Mode
• Plugins
• Themes
• Configuration Reference
• Documentation
• Contributing
• License

🤔 What is OR3?

OR3.chat is a free, open-source AI chat app built with Nuxt. It connects to OpenRouter so you can talk to hundreds of AI models — GPT-4o, Claude, Gemini, Llama, Mistral, and more — all from one place.

The big idea: you bring your own API key, and your data stays on your device by default. No middleman. No subscriptions. No tracking. Just you and the models you choose.

OR3 runs in two modes:

1. Static — a pure browser app. Zero servers, zero sign-ups. Everything lives in your browser's IndexedDB.
2. Cloud — add authentication, cross-device sync, file storage, and team workspaces by running OR3 on a server.

You start with static. When you need more, the managed @or3/cloud operator sets up the supported cloud profile for you.

✨ Core Features

Chat

• Real-time streaming with token-by-token display
• Multi-model access via OpenRouter (hundreds of models)
• Reasoning tracks — see the model's chain-of-thought when supported
• File attachments — send images and documents alongside your messages
• Branching & retry — fork conversations or regenerate any response
• Background streaming — optional cloud capability that keeps AI generating if you navigate away

Documents

• Rich text editor powered by TipTap with slash commands
• System prompts — write, save, and reuse custom instructions
• Chat-to-doc — turn any conversation into an editable document
• @mentions — reference documents or past chats inline

Workspace

• Multi-pane layout — open chats and docs side-by-side (up to 4 panes)
• Projects — organize threads and documents into groups
• Dashboard — manage models, themes, backups, images, and settings
• Full-text search — find anything across threads, docs, and projects instantly

Privacy & Control

• Local-first storage — Dexie (IndexedDB) keeps everything on your machine
• No telemetry — OR3 does not phone home
• Your API key — connect via OpenRouter OAuth (PKCE) or paste a key. Your personal key is stored in your browser and excluded from workspace sync. When used for a model request, your key is sent to the configured model endpoint, directly or through your OR3 host, depending on the request route
• Open source — GPL-3.0 licensed. Read every line, fork it, make it yours

🚀 Quick Start

New here? Start with the one-page setup guide and choose local Cloud, public Cloud, local Intern, or source development.

The supported installation path is the small @or3/cloud operator package. It uses the version-matched OR3 container and keeps the application data in a managed Docker volume.

For a private local instance:

npx @or3/cloud init --local

For a public VPS behind Caddy:

npx @or3/cloud init --public --domain chat.example.com

Node.js 20 or newer and Docker Compose v2 are required. The supported cloud profile is Basic Auth, SQLite, and filesystem storage, so no external database, authentication, or storage account is needed. See Installation and operations for prerequisites, firewall/DNS guidance, updates, backups, and recovery.

The repository-local wizard remains available for contributors who are building an editable source checkout or custom provider combination; it is not required for normal deployments.

Backups and recovery

Managed Cloud deployments keep authentication, SQLite, and uploaded files in a named /data volume. Use npx @or3/cloud backup before upgrades; the operator CLI verifies the archive and retains an immediate rollback point.

For port conflicts, missing Docker, invalid domains, provider checks, and other diagnostics, run:

npx @or3/cloud doctor

See Installation and operations for the supported local and public VPS deployment. Updating OR3 is the canonical guide for routine updates: it explains the development image workflow, updating a Docker Compose development deployment by exact digest, and the separate stable release path. Maintainers can follow Releasing OR3 Cloud for the image-first release workflow. Editable source and custom provider development still use the repository-local wizard.

⚖️ Static vs Cloud — Which Do I Pick?

OR3 ships as a static app by default. You can optionally turn on cloud mode for multi-user and multi-device features. Here's how they compare:

Start static. If you later need accounts, sync, or shared workspaces, run npx @or3/cloud init to add the supported cloud deployment; your existing browser data stays intact.

The generated first-login credentials also protect the /admin dashboard. Move them to a password manager and remove the mode-0600 credentials file.

Managed Cloud keeps bundled plugins and themes available, but does not expose upload/install or source rebuild controls. Those extension workflows require the editable source path and a deliberate trusted-code deployment.

📦 Static Mode (Default)

Static mode is the simplest way to use OR3. It generates a plain HTML/JS/CSS bundle you can host anywhere — GitHub Pages, Netlify, Vercel, Cloudflare Pages, or just open the files locally.

Build for Production

npm run generate:static

This outputs a fully static site to .output/public/. Upload that folder to any static host.

Preview the Static Build Locally

npm run preview:static

Opens a local server at http://localhost:4173.

How Static Mode Works

• All data is stored in your browser using IndexedDB (via Dexie)
• Your OpenRouter API key is stored in your browser and sent to the configured model endpoint to authenticate AI requests
• There is no backend, no database, and no authentication
• You connect to OpenRouter using OAuth PKCE (secure browser-only flow) or by pasting an API key
• Conversations, documents, prompts, files, and settings all live in your browser

Perfect for: personal use, trying out models, privacy-focused users, or hosting on free static platforms.

☁️ Cloud Mode

Cloud mode adds accounts, sync, file storage, and administration through the supported Basic Auth + SQLite + filesystem profile. Start it with the operator package:

npx @or3/cloud init --local

Use --public --domain chat.example.com on a VPS to add Caddy and automatic HTTPS. The operator also provides update, backup, restore, rollback, doctor, recover, and the narrow adopt command for an existing generated deployment. See Installation and operations for the complete workflow.

Remote OR3 Connect is currently withheld from the managed Cloud profile until its Cloudflare/domain staging flow is proved. Use Start Here for the supported local Intern path and the exact source-only boundary.

If you need an editable checkout or providers other than the supported cloud profile, use the repository-local source wizard documented in public/_documentation/cloud/or3-cloud-wizard.md.

🔌 Plugins

OR3 has a WordPress-style plugin system. You can add features without forking the project or touching core code.

What Plugins Can Do

Creating a Plugin

Plugins are Nuxt client plugins. Create a file in app/plugins/ with a .client.ts extension:

// app/plugins/my-plugin.client.ts
export default defineNuxtPlugin(() => {
    registerDashboardPlugin({
        id: 'my-plugin:hello',
        icon: 'pixelarticons:star',
        label: 'Hello World',
        description: 'My first OR3 plugin',
        order: 250,
        handler() {
            useToast().add({ title: 'Hello from my plugin!' });
        },
    });
});

That's it — restart the dev server and your tile appears on the dashboard.

Hooks System

Under the hood, plugins use an action/filter hook system (similar to WordPress). Hooks let you:

• Actions — run side effects when something happens (message sent, thread created, file uploaded)
• Filters — transform data as it flows through the system (modify AI request before sending, change how messages render)

// Listen for new messages
hooks.addAction('db:messages:after_create', ({ entity }) => {
    console.log('New message:', entity.content);
});

// Transform AI request before sending
hooks.addFilter('ai:request:filter:body', (body) => {
    body.temperature = 0.7;
    return body;
});

For authoring and release steps, see the Plugin authoring guide.

🎨 Themes

OR3 has a full theme engine that goes beyond colors. Themes can change fonts, borders, component styles, backgrounds, and even icons.

Built-in Themes

OR3 ships with several themes including a clean modern look and a retro pixel-art style. Switch themes from the dashboard at any time.

Creating a Theme

Themes live in app/theme/<name>/ and use defineTheme():

// app/theme/my-theme/theme.ts
import { defineTheme } from '../_shared/define-theme';

export default defineTheme({
    name: 'my-theme',
    displayName: 'My Theme',
    description: 'A custom look for OR3',
    colors: {
        primary: '#086DB8',
        surface: '#ffffff',
        onSurface: '#022344',
        dark: {
            primary: '#2C638B',
            surface: '#0a0a0a',
            onSurface: '#e2e2e6',
        },
    },
    fonts: {
        sans: '"Inter", system-ui, sans-serif',
        heading: '"Inter", system-ui, sans-serif',
    },
});

Theme CLI Tools

# Create a new theme from a template
bun run theme:create

# Validate your theme has no errors
bun run theme:validate

# Switch the active theme
bun run theme:switch

What Themes Can Customize

• Colors — primary, secondary, surface, and dark mode variants
• Fonts — sans, heading, mono, and base size
• Borders — radius and width tokens
• Component overrides — change default props for any Nuxt UI component based on context (e.g., "buttons inside the chat composer should be ghost style")
• CSS selectors — target specific DOM elements like the TipTap editor or code blocks
• Backgrounds — layered background effects (gradients, patterns, images)
• Icons — swap the icon set used throughout the app

For the full theme API, see the Theme Documentation.

⚙️ Configuration Reference

OR3 uses two config files at the project root:

config.or3.ts — Base Configuration

Controls branding, features, limits, and UI defaults. Works in both static and cloud mode.

config.or3cloud.ts — Cloud Configuration

Controls auth, sync, storage, rate limiting, admin, and background streaming. Only relevant when running in cloud mode.

Advanced/source deployments drive these values with environment variables. The managed Cloud CLI writes its own protected deployment state; normal users do not need to create or edit .env by hand.

📖 Documentation

Start with Start Here, then use the focused guides below.

For the complete deployment environment and provider settings matrix, see Environment and provider settings.

Full documentation lives inside the project at public/_documentation/

What's Covered

The documentation map is defined in public/_documentation/docmap.json.

🤝 Contributing

1. Fork the repo
2. Create a branch (git checkout -b my-feature)
3. Make your changes
4. Run tests (bun run test)
5. Run type-check (bun run type-check)
6. Open a pull request

Please keep changes minimal, type-safe, and consistent with the existing code style.

📄 License

OR3.chat is licensed under GPL-3.0.