owui-bridge 0.1.0

Lightweight CLI & GUI to connect local folders to OpenTerminal in OpenWebUI

⚡ OpenWebUI Bridge

Connect any local folder to OpenTerminal in one click — no Docker knowledge required.

OpenWebUI Bridge is a lightweight Windows desktop application that eliminates the need to manually run Docker commands when switching project workspaces for OpenWebUI's OpenTerminal.

---

Features

• 🚀 One-click workspace mounting — browse, select, done
• 🖥️ Desktop GUI with live Docker + container status
• ⌨️ Full CLI (owui open ., owui status, etc.)
• 📂 Windows Explorer integration — right-click any folder → Open with OpenWebUI
• 🔒 Safe — validates paths, handles failures gracefully, never exposes API keys in logs
• 🔔 Desktop notifications for every state change
• ⚙️ Persistent configuration stored in %APPDATA%\OpenWebUI Bridge\config.json
• 🔌 VS Code extension ready — the CLI is the integration surface

---

Quick Start

1. Install

# Run as Administrator
installer\install.bat

2. First Launch

Launch OpenWebUI Bridge from the desktop shortcut or Start Menu.

The setup wizard will:

1. Detect Docker Desktop
2. Validate Docker is running
3. Ask for your OpenTerminal API key, URL, and port
4. Validate Docker with a test container
5. Save configuration

3. Mount a Workspace

Via GUI: Click Browse, select your project folder, click 🚀 Mount Workspace

Via CLI:

owui open .
owui open D:\Projects\MyApp

Via Explorer: Right-click any folder → Open with OpenWebUI

---

CLI Reference

owui open [PATH]           Mount a folder as /workspace
owui open .                Mount current directory
owui restart               Restart OpenTerminal container
owui stop                  Stop OpenTerminal container
owui status                Show Docker + container status
owui config                Show current configuration
owui config --set key=val  Update a configuration value
owui logs                  Show last 100 container log lines
owui logs --lines 200      Show last 200 lines
owui gui                   Launch the desktop GUI

Configuration keys

Key	Description	Default
openWebUIUrl	URL to your OpenWebUI instance	http://localhost:3000
apiKey	OpenTerminal API key	(required)
port	Host port for OpenTerminal	8000
containerName	Docker container name	open-terminal
currentFolder	Last mounted folder path	(none)

---

How Folder Switching Works

When you select a new folder:

1. Stop the existing open-terminal container
2. Remove the container
3. Recreate it with the same name, API key, and port — bind-mounting your selected folder at /home/user
4. Health check — polls http://localhost:{port} until responding
5. Notify — desktop notification + status update

The Docker command used:

docker run -d \
  --name open-terminal \
  --restart unless-stopped \
  -p 8000:8000 \
  -v "D:\Projects\MyApp":/home/user \
  -e OPEN_TERMINAL_API_KEY=your-secret-key \
  ghcr.io/open-webui/open-terminal

The selected folder is bind-mounted directly as /home/user — no named volume, no /workspace.

No changes are required to OpenTerminal or OpenWebUI.

---

Windows Explorer Integration

After installation, right-clicking any folder shows:

📂 Open with OpenWebUI

Clicking it:

• Launches the Bridge (if not running)
• Detects the selected folder
• Mounts it as /home/user (or just opens OpenWebUI if already mounted)
• Shows a desktop notification

---

Configuration File

Stored at %APPDATA%\OpenWebUI Bridge\config.json:

{
  "openWebUIUrl": "http://localhost:3000",
  "apiKey": "your-secret-key",
  "containerName": "open-terminal",
  "port": 8000,
  "currentFolder": "D:\\Projects\\Website"
}

Security: The API key is never shown in logs or the UI (masked as abc•••••).

---

Building from Source

Requirements

• Python 3.10+
• Docker Desktop (for testing)

Build

# Install build dependencies
pip install pyinstaller

# Build single-directory (recommended)
python build.py

# Build single-file portable executable
python build.py --onefile

# Output: dist/owui/ or dist/owui.exe

Run without building

# GUI
python owui_bridge.py

# CLI
python owui_bridge.py status
python owui_bridge.py open D:\Projects\MyApp

---

VS Code Extension Integration

The CLI is designed as the single integration surface for future extensions.

A VS Code extension simply needs to:

// Mount workspace when a folder is opened
const { execSync } = require('child_process');
execSync(`owui open "${workspaceFolder.uri.fsPath}"`, { stdio: 'inherit' });

No Docker SDK, no config parsing, no container management — the Bridge handles everything.

---

Project Structure

owui-bridge/
├── owui_bridge.py              # Unified entry point (GUI + CLI)
├── build.py                    # PyInstaller build script
├── installer/
│   ├── install.bat             # Windows installer (run as admin)
│   └── uninstall.bat           # Uninstaller
└── src/
    ├── config/
    │   └── config_manager.py   # Read/write %APPDATA% config JSON
    ├── core/
    │   └── docker_manager.py   # All Docker operations
    ├── cli/
    │   └── cli.py              # owui <command> entry point
    └── gui/
        ├── main_window.py      # Desktop GUI (tkinter)
        └── explorer_integration.py  # Windows Registry context menu

---

Troubleshooting

"Docker is not running" → Start Docker Desktop and wait for it to fully initialize.

"Failed to mount workspace" → Check that the path exists and Docker has file sharing permission for that drive (Docker Desktop → Settings → Resources → File Sharing).

Context menu not appearing → Re-run installer\install.bat as Administrator.

Container not becoming healthy → Check owui logs — the container may still be pulling the image on first use. Wait a minute and try owui status again.

Config file location → %APPDATA%\OpenWebUI Bridge\config.json

Log file location → %APPDATA%\OpenWebUI Bridge\bridge.log