An Electron-based browser with an AI-powered Codex sidebar for intelligent web automation.
🌐 Website: www.gnunae.com
⚠️ Alpha Warning: This app is still in alpha stage. Do not use it in production or with sensitive data.
Maintenance note: Some historical release and maintenance details in this README may lag behind the current workflows. For Codex-first maintenance, current build/release authority, and stale-doc handling, see
AGENTS.md,docs/maintenance-playbook.md,docs/test-matrix.md, anddocs/release-checklist.md. For Codex model, runtime, and Docker sandbox failure handling, seedocs/codex-model-runtime.md.
graph TB
subgraph Electron["Electron App"]
Main["Main Process<br/>(main.ts)"]
Preload["Preload Script<br/>(preload.ts)"]
end
subgraph UI["React UI"]
App["App.tsx"]
Sidebar["CodexSidebar"]
AddressBar["AddressBar"]
BottomPanel["BottomPanel<br/>(Terminal + Output)"]
Settings["Settings"]
end
subgraph PromptEngine["Prompt Engineering"]
ModeInstr["Mode Instructions<br/>(Ask/Agent/Full)"]
PrePrompt["Pre-Prompt<br/>(System Instructions)"]
UserData["User Data Context<br/>(PDS)"]
PageContext["Page Context<br/>(URL, Title, Content)"]
UserPrompt["User Prompt"]
end
subgraph BrowserView["Browser View"]
InternalPage["Web Content"]
InternalCDP["CDP Endpoint<br/>(port 9222)"]
end
subgraph ExternalBrowser["External Browser"]
ExternalPage["Web Content<br/>(Chrome/Edge/Brave)"]
ExternalCDP["CDP Endpoint<br/>(port 9223+)"]
end
subgraph PIE["PIE - Native Mode"]
NativeCodex["Codex CLI"]
NativePlaywright["Playwright MCP"]
NativeTerminal["Native Shell<br/>(cmd/bash/zsh)"]
end
subgraph Docker["Docker - Virtual Mode"]
DockerCodex["Codex CLI"]
DockerPlaywright["Playwright MCP"]
DockerTerminal["Docker Exec<br/>(bash)"]
end
OpenAI["OpenAI API"]
Main --> Preload
Preload <--> UI
UI --> Sidebar
UI --> BottomPanel
Sidebar --> PromptEngine
PromptEngine --> |IPC| Main
Main --> |spawn| PIE
Main --> |container| Docker
BottomPanel --> |xterm.js| NativeTerminal
BottomPanel --> |xterm.js| DockerTerminal
NativeCodex --> OpenAI
DockerCodex --> OpenAI
NativeCodex --> NativePlaywright
DockerCodex --> DockerPlaywright
NativePlaywright --> |CDP| InternalCDP
NativePlaywright --> |CDP| ExternalCDP
DockerPlaywright --> |CDP| InternalCDP
DockerPlaywright --> |CDP| ExternalCDP
InternalCDP --> InternalPage
ExternalCDP --> ExternalPage
| Component | Description |
|---|---|
| Main Process | Electron main, window management, IPC handlers, Codex spawning with -c flags |
| BrowserView | Chromium-based web content rendering with CDP endpoint |
| React UI | Sidebar, address bar, terminal panel, settings overlay |
| Bottom Panel | xterm.js terminal (Native/Docker) + Output logs |
| Codex CLI | OpenAI's CLI for AI-powered automation (configured at runtime) |
| Playwright MCP | DOM interaction via Chrome DevTools Protocol (CDP) |
- 🌐 Full Browser - Chrome-based web browser with address bar and navigation
- 🪟 Multi-Window - Open multiple independent windows (Cmd/Ctrl+N)
- 📑 Multi-Tab - Multiple tabs per window with tab bar
- 💬 Chat Mode - Sidebar-only mode for use with external browsers (Chrome, Edge, etc.)
- 🔗 External Browser Support - Connect Codex to your existing browser with full automation
- 🤖 Codex Sidebar - AI assistant powered by OpenAI's Codex CLI
- 📎 File Attachments - Choose files with
+or drag them onto the Codex sidebar - 🐳 Virtual Mode - Docker-based sandbox for isolated Codex + Playwright execution
- 💻 Interactive Terminal - Full PTY emulation with xterm.js (native shell or Docker bash)
- 📋 Output Panel - View backend process logs and Codex execution status
- 📋 Task Manager - Save, schedule, and run automated tasks
- 🔐 OpenAI Auth - Sign in with your OpenAI account
- 🔧 Page Analysis - Codex can see and analyze your current page
- 🎯 MCP Integration - Model Context Protocol for browser control
- 💾 Personal Data Store (PDS) - Persistent storage for user data that Codex can access and update
- ⏰ Scheduled Tasks - Run tasks hourly, daily, or weekly at specific times
⚠️ Failure Detection - Automatic detection of CAPTCHA, 2FA, and login blocks
- Node.js 18+
- npm or yarn
- ChatGPT Pro or Plus subscription (required for Codex CLI)
- Browser navigation works without OpenAI sign-in
- Free ChatGPT accounts may not be able to use Codex features
- Upgrade at: https://chat.openai.com/settings/subscription
# Clone the repository
git clone https://github.com/fkiller/GnuNae.git
cd GnuNae
# Install dependencies
npm install
# Build the application
npm run build
# Run in development
npm run startFirst-time users can browse without signing in. Use the in-app OpenAI sign-in button when you want Codex AI features.
To use Virtual Mode, you need Docker Desktop installed. This runs Codex and Playwright in an isolated container.
GnuNae pulls ghcr.io/fkiller/gnunae/sandbox:latest before starting a sandbox.
If that pull fails but a cached image already exists, it can continue with the
cached image. Local Docker builds are mainly for development or manual recovery.
# Build the Docker sandbox image locally
npm run build:docker
# Or build without cache (recommended after updates)
npm run build:docker:clean
# Build everything (app + Docker image)
npm run build:all| Script | Description |
|---|---|
build:docker |
Build the Docker sandbox image and tag it as local + GHCR latest |
build:docker:clean |
Build Docker image without cache and tag it as local + GHCR latest |
build:all |
Build app + Docker image |
Enable Virtual Mode in Settings when Docker is detected.
GnuNae can now control your existing external browsers (Chrome, Edge, Brave, Opera) instead of using the built-in window.
- Manage Browsers: Go to Settings → External Browsers to scan for installed browsers.
- Create Shortcuts: Generate special shortcuts that launch your browser connected to GnuNae.
- Chat Mode: Launching via shortcut opens GnuNae in "Chat Mode" - a floating sidebar that attaches to your external browser.
- Full Automation: Codex can read, analyze, and control the external browser just like the built-in one.
- Launch the app - A browser window opens with a sidebar
- Navigate - Use "Browse without Codex" or the address bar to visit any website
- Sign in for Codex - Click "Sign in to OpenAI" when you want AI features
- Ask Codex - Type a prompt in the sidebar (e.g., "list all links on this page")
- Get results - Codex analyzes the page and responds
- "Summarize this page"
- "Find all job listings mentioning Python"
- "What are the main topics covered here?"
- "Google my address" (Codex will ask for your address and remember it)
- "Store all property information" (Codex extracts and saves data from the page)
The PDS allows Codex to remember your personal information across sessions:
- Automatic Prompting - When Codex needs info (email, address, etc.), a smart card appears for you to enter it
- Persistent Storage - Data is saved to
~/.gnunae/datastore.jsonand reused automatically - Web Extraction - Ask Codex to "store" information from pages (e.g., property details from Zillow)
- Manage in Settings - View, edit, or delete stored data in the Settings panel
Example workflow:
You: "Search my address on Zillow"
Codex: [Shows smart card asking for address]
You: [Enter "123 Main St, Boston MA"]
Codex: [Searches Zillow, saves address for future use]
When you send a prompt, GnuNae constructs the full prompt in this order:
| Order | Component | Description |
|---|---|---|
| 1 | Mode Instructions | Behavior constraints based on mode (Ask/Agent/Full Access) |
| 2 | Pre-Prompt | System instructions from Settings |
| 3 | User Data Context | Personal data from the Data Store |
| 4 | Page Context | Current URL, title, and page content |
| 5 | User Prompt | Your actual request |
Mode behaviors:
| Mode | Behavior |
|---|---|
| 💬 Ask | Read-only - can only describe page, refuses to click/submit/navigate |
| 🤖 Agent | Confirms critical actions (payments, final submissions, account changes) |
| ⚡ Full Access | 100% autonomous - no confirmations needed |
# macOS
npm run pack:mac
# Windows
npm run pack:win
# Linux
npm run pack:linuxFor detailed CI/CD pipeline documentation, code signing setup, and environment configuration, see:
GnuNae configures Codex CLI automatically at runtime via -c flags. No manual configuration needed - GnuNae works out of the box without modifying ~/.codex/config.toml.
If you have custom settings in ~/.codex/config.toml, GnuNae overrides Codex
spawn configuration for app-managed browser automation. Current committed code
uses the generated model list in src/core/codex-models.json, passes the
selected/default model explicitly with xhigh reasoning in Native mode, and
sends the selected model to Docker/Virtual Mode instead of relying on the Codex
CLI account default. See
docs/codex-model-runtime.md for model/runtime
failure handling and Docker parity requirements. Maintainers can run the
OpenAI model pipeline task from GitHub Actions (.github/workflows/codex-models.yml)
on demand or on its weekly schedule to regenerate the model manifest, update
Codex CLI pins across Native/package/Docker paths, refresh lockfiles, and open
a review PR.
On Windows Store updates, the bundled Node.js and Codex CLI are copied to
stable app data so an app update cannot lose them. Existing copies are compared
with the bundled version and refreshed when the Store package contains a newer
CLI. If an older CLI reports a models_cache effort error such as
unknown variant \max``, GnuNae performs one bounded runtime update and then
retries with the generated fallback model. A network or permission failure
finishes with a visible error instead of leaving the chat in an endless
“Updating Codex CLI” state. Virtual Mode uses the separately pinned Docker
sandbox image and reports when that image needs to be rebuilt or pulled.
src/
├── electron/ # Main process
│ ├── main.ts # App entry, window management, IPC handlers, Codex spawning
│ └── preload.ts # Context bridge for renderer
├── ui/ # Renderer process (React)
│ ├── index.tsx # React entry point
│ ├── App.tsx # Main UI layout
│ ├── App.css # Global styles
│ └── components/
│ ├── AddressBar.tsx # URL navigation bar
│ ├── CodexSidebar.tsx # AI assistant sidebar
│ ├── DataRequestCard.tsx # Smart card for PDS data requests
│ ├── TaskManager.tsx # Task Manager panel
│ ├── RightPanel.tsx # Chat/Task Manager wrapper
│ ├── SaveTaskCard.tsx # Save task prompt card
│ ├── TabBar.tsx # Multi-tab bar
│ ├── BottomPanel.tsx # Terminal (xterm.js) + Output logs
│ ├── Settings.tsx # Settings panel (includes PDS editor)
│ └── About.tsx # About dialog
└── core/ # Shared utilities
├── auth.ts # OpenAI authentication
├── browser-detector.ts # External browser detection (Chrome, Edge, etc.)
├── datastore.ts # Personal Data Store service
├── runtime-manager.ts # Node.js/npm/Codex runtime management
├── tasks.ts # Task service and scheduler
├── settings.ts # App settings & pre-prompt
├── schema.ts # Type definitions
├── docker-manager.ts # Docker sandbox lifecycle management
└── vault.ts # Secure storage
docker/ # Virtual Mode sandbox
├── Dockerfile # Container image definition
├── entrypoint.sh # Container startup script
├── api-server.js # REST API for Codex execution
└── playwright.config.ts # Playwright MCP configuration
docs/ # GitHub Pages (gnunae.com)
├── index.html # Landing page
├── CNAME # Custom domain
└── assets/ # Logo, videos
.github/workflows/
└── release.yml # CI/CD for multi-platform builds
- Electron - Desktop app framework
- React - UI library
- TypeScript - Type safety
- Vite - Build tool
- OpenAI Codex - AI code assistant
| Status | Feature |
|---|---|
| ✅ Done | Electron-based browser integrated with Codex-Playwright MCP |
| ✅ Done | Multi-window support with isolated Codex sessions |
| ✅ Done | Multi-tab support with tab bar |
| ✅ Done | Personal Data Store (PDS) - persistent storage with smart card UI |
| ✅ Done | Two-way PDS integration - Codex can request AND store data |
| ✅ Done | Task Manager - save, schedule, and automate tasks |
| ✅ Done | Virtual Mode - Docker sandbox for Codex + Playwright isolation |
| ✅ Done | External Browser Support (Chrome, Edge, Brave, Opera) |
| ✅ Done | Chat Mode (Sidebar-only window) |
| 🔜 Planned | Remote backend (home server, cloud) with VNC streaming |
| 🔜 Planned | Project management for multi-page workflows |
| 🔜 Planned | More LLM options including local LLM support |
- Dependency Upgrades
- Codex CLI: 0.80.0 → 0.98.0 (GPT-5.3-Codex support, steer mode stable)
- Playwright MCP: 0.0.55 → 0.0.64 (session management improvements)
- Electron: 39.2.7 → 39.5.1 (staying within v39 for stability)
- MCP SDK, React, Playwright, Zod, and other packages updated
- New AI Model: GPT-5.3-Codex
- Added to model selector (25% faster, improved agentic capabilities)
- Released by OpenAI on Feb 5, 2026
- macOS Runtime Bundling
- Node.js and Codex CLI now bundled for macOS builds (arm64 + x64)
- Docker Image Refresh
- GnuNae now pulls the rolling GHCR
latestsandbox image before Virtual Mode startup - Created periodic maintenance documentation
- GnuNae now pulls the rolling GHCR
- Interactive Terminal with xterm.js
- Full PTY emulation via node-pty (arrow keys, tab completion, Ctrl+C)
- Terminal persists when hiding/showing panel
- Renamed "Console" tab to "Output" for clarity
- Docker Terminal Support (Virtual Mode)
- Terminal connects to Docker container bash via
docker exec - Virtual Mode uses Electron's built-in CDP (no external browser required)
- Terminal connects to Docker container bash via
- Improved Runtime Manager
- Direct Node.js download using https/fs modules (no external node spawn)
- Auto-install runtime on macOS/Linux if not present
- Better shell detection (zsh, bash, sh candidates)
- Terminal Fallback
- Fallback process when node-pty fails
- Spawn debounce prevents infinite restart loop
- Embedded Node.js & Codex CLI
- Windows: Node.js 22 LTS and Codex CLI bundled in package
- macOS: Downloads Node.js and Codex to ~/Library/Application Support/GnuNae on first run
- Settings UI shows runtime status (Node.js, npm, Codex CLI versions) under Native Mode
- Downgraded electron-builder to 24.13.3 for compatibility
- Cross-Platform Runtime Scripts
- Added
scripts/download-node.jsfor portable Node.js download - Added
scripts/install-codex.jsfor local Codex CLI installation - RuntimeManager service for validation and path resolution
- Added
- GitHub Actions updated for Windows builds with embedded runtime
- Chat Mode & External Browsers
- Support for External Browsers: Use Chrome, Edge, Brave, or Opera with GnuNae.
- Chat Mode Window: Minimized sidebar-only interface when using external browsers.
- CDP Integration: Real-time two-way control of external browsers via Chrome DevTools Protocol.
- Docker & Chat Mode: Fixed complex CDP connection issues allowing Dockerized Codex to control external browsers via
host.docker.internal. - Standalone Settings: Settings now open in a dedicated window in Chat Mode.
- Shortcuts: Auto-generate shortcuts for your installed browsers with GnuNae integration.
- Virtual Mode (Docker Sandbox)
- Enables isolated execution of Codex CLI and Playwright MCP in a Docker container
- Requires Docker Desktop installed on your machine
- Shares OpenAI authentication with the container securely
- Mounts working directory so attached files are accessible
- Foundation for future remote backend support (home server, cloud)
- Toggle via Settings panel when Docker is detected
- Bug fixes and stability improvements for multi-window support
- Multi-Window Support
- Open multiple independent GnuNae windows (Cmd/Ctrl+N)
- Each window has isolated Codex sessions and working directory
- Window-specific tab management and automation
- Playwright MCP correctly targets each window's webview
- Stability Improvements
- Fixed iframe navigation polluting address bar URL
- Protected application UI from accidental Playwright navigation
- Improved tab selection guidance in pre-prompt
- Bug fixes for task execution and UI improvements
- Task Execution System
- Save prompts as reusable tasks with one-time, on-going, or scheduled triggers
- Task Manager panel with favorites, running tasks, and scheduled countdowns
- Background scheduler for automated task execution
- Max concurrency setting (1-5 simultaneous tasks)
- Failure Handling
- CAPTCHA/2FA/login detection with warning cards
- Menu Enhancements
- Settings accessible from App menu (⌘,)
- View menu: Show Chat (⌘1), Task Manager (⌘2), Hide Panel (⌘0)
- About dialog with open source library attributions
- UI Improvements
- Chat/Task Manager toggle buttons in address bar
- Collapsible right panel with dynamic browser resizing
- Personal Data Store (PDS) with smart card UI
- Multi-tab browser support
- Initial release
- Codex sidebar with OpenAI integration
- MCP-based browser automation
MIT
Contributions welcome! Please open an issue or PR.
Built with ❤️ for AI-powered browsing