Dynobox

A local-first, keyboard-driven email client for people who live in their inbox.

Dynobox is a personal email client that is dark by default and ships as both a browser app and an Electron desktop app named DYNO BOX. It supports Gmail OAuth, Outlook presets, custom IMAP/POP3 + SMTP accounts, local desktop mail storage, and an optional AI assistant currently surfaced in the UI as BRAIN BOX. Some internal APIs and environment variables still use the historical REX name.

Highlights

Focus	What Dynobox Provides
Local-first mail	Browser mode through the local Express API, desktop mode through Electron IPC and SQLite.
Keyboard workflow	Fast inbox navigation, search, compose, archive, trash, star, and read/unread actions.
Provider flexibility	Gmail OAuth plus Outlook presets and custom IMAP/POP3 + SMTP accounts.
Optional AI	BRAIN BOX chat, summaries, draft help, transcription, semantic search, BYOK, gateway, and Ollama paths.
Open-source ready	Apache-2.0 license, public security notes, architecture docs, contribution guide, and CI checks.

Contents

• Project Status
• Features
• Requirements
• Quick Start
• Desktop Mode
• Environment
• Scripts
• Security and Privacy

Project Status

Dynobox is being prepared for public development. Expect sharp edges around desktop packaging, provider coverage, and AI workflows. Please avoid using the app with irreplaceable production mailboxes until you have reviewed the security and privacy notes below.

Features

• Gmail OAuth account connection and Gmail thread actions.
• Manual Outlook, IMAP, POP3, and SMTP account setup.
• Keyboard-first inbox navigation, compose, archive, trash, star, read/unread, and search.
• Electron desktop mode with SQLite-backed local mail state through IPC.
• Optional BRAIN BOX AI chat, summaries, draft assistance, transcription, semantic search, and MCP tooling.
• Optional local Ollama mode for AI chat, alongside BYOK and platform gateway modes.

Requirements

• Node.js 20 or newer.
• npm 10 or newer.
• Google OAuth credentials for Gmail support.
• Native build tooling for desktop mode because better-sqlite3 is used by Electron. On macOS this usually means Xcode Command Line Tools; Windows and Linux need their normal Node native module toolchains.

Repository Layout

client/      React + Vite + Tailwind renderer
server/      Express API for auth, Gmail/manual mail, REX/BRAIN BOX, and MCP
electron/    Electron main/preload process, IPC, SQLite, and desktop integration
docs/        Architecture, MCP, AI policy, and implementation notes
scripts/     Runtime build helpers

See docs/ARCHITECTURE.md for the web, desktop, AI, and MCP data flows.

Quick Start

Install all workspaces:

npm install
npm install --prefix client
npm install --prefix server

Create a server environment file:

cp server/.env.example server/.env

Edit server/.env with your Google OAuth credentials:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
PORT=3001
CLIENT_URL=http://localhost:5173

Start the browser app and API:

npm run dev

Open http://localhost:5173, connect a Gmail account, and complete the OAuth flow.

Google OAuth Setup

1. Open Google Cloud Console.
2. Create or select a project.
3. Enable the Gmail API under APIs & Services -> Library.
4. Create an OAuth 2.0 Client ID with application type Web application.
5. Add http://localhost:3001/auth/callback as an authorized redirect URI.
6. Copy the client ID and client secret into server/.env.

The local server builds the OAuth redirect URL from PORT. If you run Dynobox on a non-localhost host, you must configure matching redirect URIs and review the remote access warnings in SECURITY.md.

Desktop Mode

Development desktop mode starts the server, Vite, and Electron shell:

npm run dev:desktop

Production-like desktop mode builds the renderer/runtime and starts Electron:

npm run build:desktop
npm run start:desktop

If Electron native modules are stale after install, rebuild them:

npx electron-rebuild -f -w better-sqlite3

Desktop SQLite lives under Electron's userData directory, for example ~/Library/Application Support/DYNO BOX/dynobox.sqlite on macOS. OAuth tokens and manual account credentials for web mode are stored in server/.tokens.json.

Environment

Server configuration is documented in server/.env.example. Common values:

PORT=3001
CLIENT_URL=http://localhost:5173
TOKEN_ENCRYPTION_KEY=optional_long_random_secret
DYNOBOX_API_KEY=optional_shared_secret
ALLOW_REMOTE_CLIENT=false
TRUST_PROXY=false

Client configuration is documented in client/.env.example. Desktop local-core mode uses:

VITE_USE_LOCAL_CORE=true

Optional AI configuration:

REX_PLATFORM_API_KEY=optional_platform_provider_key
VERCEL_AI_GATEWAY_API_KEY=optional_platform_provider_key
AI_GATEWAY_API_KEY=optional_platform_provider_key
REX_GATEWAY_PROVIDER=openai
REX_MODEL=google/gemini-2.5-flash-lite
REX_MAX_OUTPUT_TOKENS=500
REX_GATEWAY_BASE_URL=https://ai-gateway.vercel.sh/v1
REX_ANTHROPIC_BASE_URL=https://api.anthropic.com
REX_OLLAMA_BASE_URL=http://127.0.0.1:11434
REX_OLLAMA_MODEL=llama3.2:latest
REX_OLLAMA_KEEP_ALIVE=30m
REX_OLLAMA_CHAT_TIMEOUT_MS=35000
REX_OLLAMA_CONTEXT_TIMEOUT_MS=5000
REX_EMBEDDING_MODEL=text-embedding-3-small
REX_TRANSCRIBE_MODEL=gpt-4o-mini-transcribe
REX_SETTINGS_ENCRYPTION_KEY=optional_long_random_secret

Optional Electron environment:

ELECTRON_START_URL=http://localhost:5173
DYNOBOX_SERVER_BASE_URL=http://localhost:3001
DYNOBOX_API_KEY=the_same_shared_secret_if_enabled
DYNOBOX_SUPPRESS_CHROMIUM_WARNINGS=true
DYNOBOX_DISABLE_HARDWARE_ACCELERATION=false

See docs/rex-ai-policy.md before enabling AI features with real email data.

Scripts

npm run dev                 # server + client
npm run server              # server only
npm run client              # client only
npm run dev:desktop         # server + client + Electron
npm run build:desktop       # client dist + runtime JS
npm run build:runtime       # server/.build + electron-build
npm run lint                # client ESLint
npm run check               # lint + client build + runtime build

Client-only scripts:

npm run dev --prefix client
npm run build --prefix client
npm run lint --prefix client

Server-only scripts:

npm run dev --prefix server
npm run build --prefix server
npm run start --prefix server

Keyboard Shortcuts

Key	Action
j / Down	Next thread
k / Up	Previous thread
Enter	Open thread
e	Archive
#	Trash
r	Reply
a	Reply all
c	Compose
/	Search
s	Star
u	Mark unread
Cmd+Enter	Send in compose
Esc	Close compose

Security and Privacy

Dynobox handles mailbox contents, OAuth refresh tokens, manual mail passwords, local SQLite databases, and optional AI provider keys. Read SECURITY.md and docs/rex-ai-policy.md before using it with sensitive mail.

Important defaults:

• Local server access is loopback-only unless ALLOW_REMOTE_CLIENT=true.
• DYNOBOX_API_KEY can add a shared local API key for HTTP requests.
• TOKEN_ENCRYPTION_KEY enables encryption for token files that support it.
• BRAIN BOX may send selected email content to configured AI providers when enabled.
• MCP is intended for local automation and should not be exposed without strong controls.

Never commit .env, .tokens.json, .mcp-settings.json, .rex-settings.json, generated out/ builds, or desktop SQLite databases.

Contributing

See CONTRIBUTING.md for setup, branch, PR, generated output, and documentation expectations.

License

Dynobox is licensed under the Apache License 2.0.