Features

🔐 Self-hosted & private

Your code, API keys, and conversation history stay on your own machine. No cloud, no third party, no data leakage.

🧠 Multi-LLM support

Works with Anthropic Claude, OpenAI GPT/o1/o3, DeepSeek, Google Gemini, Mistral, Groq, xAI, OpenRouter, and more — including local models.

📁 Full file management

Built-in file browser with CodeMirror editor supporting 10+ languages. Create, edit, search files right in the browser.

🖥️ Integrated terminal

Full terminal emulator via xterm.js + WebSocket. Multiple tabs, reconnect support, resizable layout.

🔀 Git integration

View diffs, stage changes at hunk level, explore commit history with git-graph — all from the browser.

🔌 MCP protocol support

Connect external MCP servers and expose their tools to your coding agent. Supports both global and project-level configurations.

📱 Mobile-friendly + PWA

Responsive design works on iOS/Android. Install as a PWA for a native-like experience.

🎨 Fully customizable theme

Dark and light themes controlled by CSS variables. Create your own skin without rebuilding.

📦 Docker & K8s ready

Dockerfile, docker-compose, Kubernetes and OpenShift deployment manifests included.

Getting Started

Quick Start (no install required)

npx huiyu-piwebui-forge

Opens your browser at http://localhost:9144. Provider API keys go into Settings → Providers.

One-time global install (faster subsequent launches)

npm install -g huiyu-piwebui-forge
huiyu-piwebui-forge

# Override defaults via flags:
huiyu-piwebui-forge --port 4000 --workspace-path ~/Code
huiyu-piwebui-forge --api-key @/run/secrets/api-key --no-expose-docs
huiyu-piwebui-forge --help       # full flag table

Prerequisites

• Node.js 18+
• An API key from a supported provider (Anthropic, OpenAI, DeepSeek, Google, etc.)

One-click Start (Windows)

Clone the repo, double-click start.bat — the script installs everything and opens your browser at http://localhost:9145.

One-click Start (macOS / Linux)

Clone the repo, run bash start.sh from the terminal — the script installs everything and opens your browser at http://localhost:9145.

Manual Start

git clone https://github.com/huiyu9144/Huiyu-PiwebUI-Forge.git
cd Huiyu-PiwebUI-Forge
npm install
npm run dev

• Client (dev server with hot reload): http://localhost:9145
• API server: http://localhost:9144

API Key Setup

Create ~/.pi/agent/auth.json:

{
  "deepseek": {
    "type": "api_key",
    "key": "sk-your-api-key-here"
  }
}

Or set an environment variable:

# Windows
set DEEPSEEK_API_KEY=sk-your-api-key

# macOS/Linux
export DEEPSEEK_API_KEY=sk-your-api-key

Supported providers: Anthropic, OpenAI, DeepSeek, Google, Mistral, Groq, xAI, OpenRouter, and more.

Customization

The theme is controlled by CSS custom properties in src/globals.css. Override the variables to create your own skin:

:root {
  --bg-primary: #0a0a0a;
  --accent: #60A5FA;
  /* ... */
}

html[data-theme="light"] {
  --bg-primary: #ffffff;
  --accent: #2563EB;
  /* ... */
}

Tech Stack

| Layer | Technologies | |-------|-------------| | Frontend | React 19, TypeScript, Vite 6, Tailwind CSS v4, Zustand, CodeMirror 6 | | Backend | Fastify 5, WebSocket, SSE, JWT | | Terminal | xterm.js + node-pty | | Infrastructure | Docker, docker-compose, Kubernetes, GitHub Actions |

Community

• 💬 Join our Discord — ask questions, share tips, connect with users and contributors.
• ⭐ Star us on GitHub — it helps others discover the project.

Acknowledgments

This project is built on top of two open-source projects:

• pi-forge by Devin Marks and contributors — the self-hosted browser UI for the Pi coding agent.
• pi by earendil-works and contributors — the core Pi coding agent SDK and CLI.

License

MIT — see the upstream projects for their licenses:

• pi-forge
• pi