gem-hunter
Language: TypeScript
This is a WebUI interface based on CLI-Proxy-API, designed to simplify configuration modifications and runtime status monitoring.
Your proxy, at a glance. Your configuration, in control.
A lightweight Web UI for CLI Proxy API.
Manage providers, credentials, quotas, and logs — from a single HTML file.
English · 简体中文
From everyday configuration to troubleshooting, keep the essentials close at hand.
| Configure | Connect | Observe |
|---|---|---|
| Edit settings visually or in YAML, with a diff before saving. | Manage provider keys, auth files, and OAuth flows. | Check instance status, provider quotas, and request logs. |
Single-file deployment · Responsive layout · Four UI languages
Important
Requires CLI Proxy API ≥ 8.0.0; the latest v8 release is recommended. This repository is the management UI, not the proxy — it does not forward traffic. It uses the v8 Management API (/v8/management) and v8 configuration layout, with no v0 fallback. Plugin resources and custom extensions retain their backend-declared paths.
The UI is bundled with CLI Proxy API. No separate frontend deployment is needed for the standard setup.
http://<host>:<api_port>/management.html.The API address is detected from the page URL and can be changed manually.
Note
The management key signs you into this UI. Client keys in access.api-keys authorize requests to the proxy — they are not interchangeable.
The UI accepts addresses such as localhost:8317, https://example.com:8317, or http://example.com:8317/v8/management; the management suffix is removed automatically.
Management requests use Authorization: Bearer <MANAGEMENT_KEY>. Remote access may require management.allow-remote: true on the server. See the backend documentation for authentication rules and server-side limits.
Upgrade the backend first and back up config.yaml. The backend returns the v8 configuration layout on reads; a successful v8 configuration write migrates the stored file. The editor only writes v8 fields:
access.api-keys: client keys for accessing the proxy.api-keys: upstream provider groups.| Area | What you can do |
|---|---|
| Dashboard | See connection status, server version, build date, and model availability at a glance. |
| Configuration | Edit common settings and client keys visually, or use the YAML editor with search, highlighting, and a save diff preview. |
| AI providers | Configure Gemini, Codex, Claude, Vertex, and OpenAI-compatible providers; manage keys, headers, proxies, and model mappings. |
| Auth files & OAuth | Upload, download, and organize credentials; connect supported providers with OAuth or device flows; manage model aliases and exclusions. |
| Quotas | Inspect quota and usage information for supported providers, including Claude, Antigravity, Codex, Kimi, and xAI/Grok. |
| Logs | Follow logs with auto-refresh, search, hide management traffic, and download request error logs. |
| Plugins | Access plugin management when the connected backend advertises support. |
| System | Check for updates, inspect available models, and clear local login data. |
Supports English, 简体中文, 繁體中文, and Русский, with browser-language detection and a manual language switch. Responsive layouts support desktop, tablet, and mobile use in modern Chrome, Firefox, Safari, and Edge.
To build your own single-file UI, use Bun 1.4.3:
bun install --frozen-lockfile bun run build
The output is dist/index.html, with JavaScript, CSS, and bundled assets inlined. The release workflow renames it to management.html for backend hosting.
Use bun run preview to preview locally. Prefer an HTTP server over opening the file via file://, which can encounter browser CORS restrictions.
vX.Y.Z trigger the release workflow.VERSION, then git tags, then the package version, with dev as the final fallback.bun install --frozen-lockfile bun run dev
Open http://localhost:5173 and connect to your backend instance.
Built with React 19 · TypeScript 6 · Vite 8 · Zustand · Axios · React Router 7 · Motion · CodeMirror 6 · SCSS Modules · i18next.
| Command | Purpose |
|---|---|
bun run dev |
Start the Vite dev server |
bun run build |
TypeScript compilation + production build |
bun run preview |
Serve the build locally |
bun run test |
Run Bun tests |
bun run lint |
Run ESLint; warnings are not treated as failures |
bun run type-check |
Run tsc --noEmit |
bun run verify |
Run tests, lint, and build |
bun run format |
Format source files with Prettier |
Issues and PRs are welcome. Include reproduction steps, backend and UI versions, screenshots for UI changes, and verification results. See AGENTS.md for repository conventions.
Treat the management key as a secret. When remember password is enabled, it is persisted in browser storage using reversible obfuscation — not encryption.
Use a trusted device or dedicated browser profile. Enable remote management only after evaluating the exposure of your server.
Connection or authentication problems/v1/models requires at least one proxy API key.