Rox

A lightweight ActivityPub server & client with Misskey API compatibility

Languages: English | 日本語

---

Highlights

⚡	🖥️	🌐	🔒
Lightning Fast	Infrastructure Agnostic	Fully Federated	Secure by Design
Built with Bun runtime for maximum performance	Run on VPS, Docker, or edge environments	Connect with Mastodon, Misskey, and more	Passkey, OAuth, role-based permissions

Features

• Lightweight & High Performance - Built with Bun runtime and modern web standards
• Infrastructure Agnostic - Run on traditional VPS (Docker) or edge environments (Cloudflare Workers/D1)
• Misskey API Compatible - Seamless migration for existing Misskey users
• Multi-Database Support - PostgreSQL, MySQL, SQLite/D1
• Flexible Storage - Local filesystem or S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
• Multiple Auth Methods - Password, Passkey (WebAuthn), and OAuth (GitHub, Google, Discord, Mastodon)
• Full ActivityPub Support - Federation with Mastodon, Misskey, GoToSocial, and more
• Role-Based Permissions - Misskey-style policy system with granular access control
• Plugin System - Extensible architecture with event hooks, custom routes, and frontend slots
• Time-Series Charts - Optional statistics subsystem with automatic TimescaleDB detection
• Internationalization - English and Japanese support out of the box

Screenshots

Click to view screenshots

Coming soon

Quick Start

Prerequisites

• Bun >= 1.0.0
• Docker and Docker Compose (for local development)
• PostgreSQL >= 14 (or MySQL >= 8.0, or SQLite)

Installation

# Clone the repository
git clone https://github.com/Love-Rox/rox.git
cd rox

# Install dependencies
bun install

# Setup environment variables
cp .env.example .env
# Edit .env with your configuration

# Start development services (PostgreSQL + MariaDB + Dragonfly)
docker compose -f docker/compose.dev.yml up -d

# Run database migrations
bun run db:generate
bun run db:migrate

# Start development servers
bun run dev

The backend API will be available at http://localhost:3000 and the frontend at http://localhost:3001.

Project Structure

rox/
├── packages/
│   ├── backend/   # Hono Rox (API server)
│   ├── frontend/  # Waku Rox (web client)
│   └── shared/    # Common types and utilities
├── docs/          # Documentation
├── docker/        # Docker configurations
└── scripts/       # Build and deployment scripts

Technology Stack

Backend (Hono Rox)

Category	Technology	Purpose
Runtime	Bun	Fast JavaScript runtime, package manager, test runner
Language	TypeScript	Type safety and development efficiency
Framework	Hono	Ultra-lightweight web framework
ORM	Drizzle ORM	TypeScript-first ORM
Queue	Dragonfly / BullMQ	Async job processing
Code Quality	oxc	Linting and formatting

Frontend (Waku Rox)

Category	Technology	Purpose
Framework	Waku	React Server Components framework
State Management	Jotai	Atomic state management
UI Components	React Aria	Accessible headless UI
Styling	Tailwind CSS v4	Utility-first CSS with OKLCH color space
Internationalization	Lingui	3kb optimized i18n

Development

Available Scripts

Script	Description
bun run dev	Start all development servers
bun run build	Build all packages
bun run test	Run tests
bun run lint	Lint code with vp (oxc)
bun run format	Format code with vp (oxc)
bun run typecheck	Type check all packages
bun run db:generate	Generate database migrations
bun run db:migrate	Run database migrations
bun run db:studio	Open Drizzle Studio

Database Configuration

PostgreSQL (Default)

DB_TYPE=postgres
DATABASE_URL=postgresql://rox:rox_dev_password@localhost:5432/rox

MySQL/MariaDB

# MariaDB is included in the dev compose
docker compose -f docker/compose.dev.yml up -d

DB_TYPE=mysql
DATABASE_URL=mysql://rox:rox_dev_password@localhost:3306/rox

SQLite

DB_TYPE=sqlite
DATABASE_URL=sqlite://./rox.db

Charts / Time-Series Statistics

Optional charts subsystem (with TimescaleDB)

The charts subsystem records hourly/daily snapshots of instance statistics (users, notes, active users, federation, drive). It is disabled by default.

# Enable the subsystem
CHARTS_ENABLED=true

# Backend selection: auto | postgres | timescale
# `auto` detects the TimescaleDB extension at startup and uses it when
# available, otherwise falls back to plain PostgreSQL.
CHARTS_BACKEND=auto

TimescaleDB is optional. To run it locally, start the timescale profile and point DATABASE_URL at it (port 5433):

docker compose -f docker/compose.dev.yml --profile timescale up -d
DATABASE_URL=postgresql://rox:rox_dev_password@localhost:5433/rox
bun run db:migrate

With CHARTS_BACKEND=auto, the extension is detected automatically — no extra configuration required.

Storage Configuration

Local Storage (Development)

STORAGE_TYPE=local
LOCAL_STORAGE_PATH=./uploads

S3-Compatible Storage

STORAGE_TYPE=s3
S3_ENDPOINT=https://your-account.r2.cloudflarestorage.com
S3_BUCKET_NAME=rox-media
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=auto

OAuth Configuration

GitHub, Google, Discord, Mastodon

GitHub

GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_REDIRECT_URI=https://your-domain.com/api/auth/oauth/github/callback

Google

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://your-domain.com/api/auth/oauth/google/callback

Discord

DISCORD_CLIENT_ID=your-client-id
DISCORD_CLIENT_SECRET=your-client-secret
DISCORD_REDIRECT_URI=https://your-domain.com/api/auth/oauth/discord/callback

Mastodon

MASTODON_CLIENT_ID=your-client-id
MASTODON_CLIENT_SECRET=your-client-secret
MASTODON_INSTANCE_URL=https://mastodon.social
MASTODON_REDIRECT_URI=https://your-domain.com/api/auth/oauth/mastodon/callback

Architecture

Rox uses the Repository Pattern and Adapter Pattern to decouple business logic from infrastructure concerns:

┌─────────────────────────────────────────────────────────────┐
│                      Hono Routes                            │
├─────────────────────────────────────────────────────────────┤
│                    Business Services                         │
├─────────────────────────────────────────────────────────────┤
│          Repository Interfaces │ Adapter Interfaces          │
├────────────────────────────────┼────────────────────────────┤
│  PostgreSQL │ MySQL │ SQLite   │  Local │ S3 │ R2           │
└────────────────────────────────┴────────────────────────────┘

• Repository Pattern: Database operations are abstracted through interfaces
• Adapter Pattern: Storage operations use adapters for different backends
• Dependency Injection: Implementations are injected via Hono Context

See Implementation Guide for detailed architectural documentation.

Implementation Status

Phase	Status	Description
Phase 0	✅ Complete	Foundation (Database, Storage, DI)
Phase 1	✅ Complete	Misskey-Compatible API
Phase 2	✅ Complete	Frontend (Waku Client)
Phase 3	✅ Complete	ActivityPub Federation
Phase 4	✅ Complete	Refactoring & Optimization
Phase 5	✅ Complete	Administration & Security
Phase 6	✅ Complete	Production Readiness
Phase 7	✅ Complete	Plugin System

View detailed implementation status

Phase 2: Frontend

• ✅ Waku + Jotai setup
• ✅ Tailwind CSS v4 with OKLCH colors
• ✅ React Aria Components
• ✅ Lingui i18n (English/Japanese)
• ✅ Authentication (Passkey + Password + OAuth)
• ✅ Timeline with infinite scroll
• ✅ Note Composer (text, images, CW, visibility)
• ✅ User interactions (reply, reaction, follow)
• ✅ File uploads (drag & drop, preview)
• ✅ User profile pages
• ✅ Image modal (zoom, pan, gallery)
• ✅ Full accessibility support

Phase 3: ActivityPub

• ✅ WebFinger (RFC 7033)
• ✅ Actor documents (Person, JSON-LD)
• ✅ HTTP Signatures (RSA-SHA256, hs2019)
• ✅ Inbox (11 activity types)
• ✅ Outbox & Collections
• ✅ Activity delivery queue
• ✅ Shared inbox support
• ✅ Federation tested with Mastodon, Misskey, GoToSocial

Phase 5: Administration

• ✅ Role-based permission system
• ✅ User management API
• ✅ Instance block management
• ✅ Invite-only registration
• ✅ User report system
• ✅ Instance settings management

Phase 7: Plugin System

• ✅ EventBus for typed event hooks
• ✅ Plugin loader with lifecycle management
• ✅ Database-backed configuration storage
• ✅ Custom route registration (/api/x/{pluginId}/)
• ✅ Frontend plugin slots (19 locations)
• ✅ Admin plugin management UI
• ✅ Sample hello-world plugin

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting PRs.

Key Points:

• TSDoc comments must be in English
• Follow the Repository and Adapter patterns
• Run bun run lint && bun run typecheck && bun test before submitting
• Use conventional commit messages

License

MIT

Links

Resource	Description
Contributing Guidelines	How to contribute
DevContainer Guide	VS Code/Cursor DevContainer setup
Project Specification	Original spec (Japanese)
Implementation Guide	Architecture details
Plugin Development	How to create plugins
Testing Guide	Testing documentation
Deployment Guide	Production deployment

---

Made with ❤️ by the Rox community