AMC-WebUI: a Gemini console that runs in the browser and refuses Node 27
A local-first AI workflow WebUI for Gemini, integrating multimodal chat, Canvas, file processing, real-time search, code execution and advanced reasoning.
At a glance
- What is it?
- A TypeScript, local-first web console for Gemini with an OpenAI-compatible path, three deployment shapes and a Node engine window that stops at 26, where the interesting decisions sit in the environment defaults rather than the feature list.
- Who is it for?
- This is a substantial single-owner project with an unusually honest security posture written into its own defaults: MCP transports off, private-network forwarding off, the API port exposed rather than published, and a plain statement that the default configuration is not an internet-facing gateway. Two things decide whether it fits.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- yeahhe365/AMC-WebUI932 ★ · +41
| Repository | 2026-08-27 | 2026-11-15 |
|---|---|---|
| yeahhe365/AMC-WebUI | 891 | 932 |
41 Stars in the last 80 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
engine-strict turns a wrong Node version into a failed install
The package manifest pins the runtime window with `engines: >=24 <27` and the project enables `engine-strict`, so the boundary is enforced rather than advisory. Node 27 and above, or 23 and below, fails `pnpm install` outright instead of printing a warning. The repository ships a `.nvmrc` and the suggested remedy is `nvm use` before anything else.
The recommended version is Node 26 and the floor is 24. The main CI workflow runs on the same major as `.nvmrc`, which is how the two stay aligned, and the container images are built on `node:24-slim`, so the Docker path runs the oldest supported major while local development runs the newest. Dependencies are managed with pnpm, declared as `[email protected]` in `packageManager` and locked by `pnpm-lock.yaml`, with npm accepted for `npm ci`.
The initial checkout is three commands:
git clone https://github.com/yeahhe365/AMC-WebUI.git
cd AMC-WebUI
pnpm install
pnpm devThe dev server listens on `http://localhost:5175`, which is one port away from the default Docker entry point at `http://localhost:8080`. The API service listens on 3001 inside the compose network. There is also a `build:analyze` script that writes `dist/bundle-stats.html` showing the main bundle, the lazy-loaded chunks and the PWA precache boundary, which is the quickest way to see what the local-first runtime is actually shipping.
Chat history, Python and artifacts all stay in the browser
The project is local-first in a literal sense. Chat data is stored in browser IndexedDB by default, cross-tab synchronisation runs over BroadcastChannel, and the Web Locks API guards IndexedDB writes so two tabs do not corrupt each other. A PWA manifest, service worker and install or update prompts let the app open offline as a shell, though runtime requests stay network-first and model responses still need a connection.
The heaviest local piece is a Python sandbox built on Pyodide running WebAssembly, with numpy, pandas and matplotlib preloaded. It detects code dependencies and installs scipy or scikit-learn on demand, supports mounting files and downloading generated ones, and captures matplotlib output automatically. Alongside it sit browser-side audio preprocessing and compression to reduce upload tokens and bandwidth, ZIP or folder drop with automatic codebase structure parsing, a per file type choice between the Gemini Files API and direct Base64 upload, and input detail levels of unspecified, Low, Medium or High, with Ultra High available for a single image.
Live Artifacts takes code blocks from a response and renders them as interactive HTML previews that go fullscreen automatically, with safe inline HTML and SVG, form controls, follow-up interaction, Mermaid and Graphviz rendering, plus an automatic generation mode whose trigger model, prompt version and custom prompt are all configurable. Transcription runs through the Gemini 3.5 Transcribe model, text to speech offers 30 voices, and image generation supports aspect ratio, size and four-image output. The interface ships in seven languages, English, Chinese, Japanese, Korean, Spanish, French and German, across four themes with Pearl as the default light one.
The README in this repository is written in Chinese, with an English version, `README.en.md`, listed beside it at the root.
Three places hold an API key, and one flag decides which one is used
A single build accepts credentials from three directions, and the documentation treats them as separate concerns rather than alternatives.
The first is the browser. Keys typed into Settings, under providers and API, stay in the browser and are the default path in Docker. The second is `.env.local` at the repository root, which applies to frontend development only:
VITE_GEMINI_API_KEY=your_api_key_here
VITE_OPENAI_API_KEY=your_openai_compatible_key_hereThe third is server side, in environment variables. `GEMINI_API_KEY` covers regular server-managed Gemini requests, `LIVE_GEMINI_API_KEY` is a dedicated key for the Live API that falls back to `GEMINI_API_KEY` when unset, and `GEMINI_API_BASE` defaults to `https://generativelanguage.googleapis.com`. `THIRD_PARTY_ROUTES` takes a JSON object mapping a provider id to a `baseUrl` and an `apiKey` pair, so third-party secrets can arrive as one env value rather than as user settings. The example in `.env.example` accepts only https and non-private hosts.
Which of the two wins is a single boolean. `SERVER_KEY_PRIORITY=false` by default means the browser BYOK key is used and the server key is only a fallback; set to true and the server key wins with the browser key as fallback. That flag applies to all three chains, Gemini, Live and third-party. The Gemini proxy can also be pointed at a custom endpoint through the SDK's own `baseUrl` setting.
The compose default is an empty password gate on a trusted-network assumption
The compose file is more interesting than the port numbers. `ACCESS_PASSWORD` defaults to empty and `SERVER_ACCESS_TOKEN`, its alias, also defaults to empty; `ALLOWED_ORIGINS` is empty as well, which suits same-origin use and nothing else. The password is described as a gatekeeper that, once set, requires every client request under `/api/*` to carry it. On the web side `RUNTIME_SERVER_MANAGED_API` defaults to true, `RUNTIME_SERVER_ACCESS_PASSWORD` is empty and `RUNTIME_USE_CUSTOM_API_CONFIG` defaults to true.
So the shipped default is a service with no password in front of its API, which the project says so itself. That configuration is positioned as a trusted self-hosted deployment, and the documentation states plainly that the default BYOK mode is not sufficient to serve as an unauthenticated multi-user API gateway on the public internet. Putting it online means adding authentication, quota and rate limiting, abuse protection, auditing and tenant isolation yourself.
The shape of the deployment limits the exposure. The `api` service uses `expose` for port 3001 rather than publishing it, so the API is reachable through the web container's reverse proxy and not directly from the host. `web` waits for `api` to report healthy, which is a fetch against `http://127.0.0.1:3001/health` every 10 seconds with a 5 second timeout, 3 retries and a 5 second start period, and both services restart unless stopped. Images default to `ghcr.io/yeahhe365/amc-webui-api:latest` and `ghcr.io/yeahhe365/amc-webui-web:latest`, and the web image bundles a `dist/` you built on the host rather than running a production build inside the container. After changing front end or API code the order matters: `pnpm run build:docker`, then `docker compose up -d --build`.
The OpenAI-compatible path stops at chat/completions and shares no tools
Gemini native mode is the main path, and it is where Thinking, the Live API, the Gemini Files API, Deep Search, Google Search, code execution and image generation live. The OpenAI-compatible mode is a separate lane aimed at plain chat, with its own API key, its own base URL and its own model list. Requests go to `POST {Base URL}/chat/completions`, and the application appends that suffix, which is why the base URL has to be the interface root such as `https://api.openai.com/v1` rather than the completions path itself. Gemini's own compatible endpoint is given as `https://generativelanguage.googleapis.com/v1beta/openai`, and the provider list in settings includes OpenAI, DeepSeek, Anthropic and OpenRouter, with a button to test connectivity and latency and a step to sync or edit the model list.
Two limits are stated rather than left to be discovered. The compatible mode does not overwrite the native Gemini configuration, because the two sets of keys are stored separately and the model lists are maintained independently. And it does not run the Gemini native toolchain at all, so any Gemini-specific capability belongs to native mode regardless of which path a prompt looks like it takes. Non-streaming and streaming responses both work, and system prompt, `temperature` and `top_p` carry over.
The multi-key rotation feature applies to both sides, Gemini native and OpenAI-compatible, so a single provider entry can hold more than one key.
MCP transports and private-network forwarding are two separate switches, both off
Model Context Protocol support is served through the Node API under `/api/mcp/*`, with three transports available: stdio, SSE and Streamable HTTP. On the API container the switches start closed. `ENABLE_MCP_STDIO=false` and `ENABLE_MCP_PRIVATE_HTTP=false`, and the private HTTP flag is what guards the SSE and HTTP path. The comment in `.env.example` says to enable them only for trusted self-hosted deployments.
A third switch guards a different risk. `ENABLE_THIRD_PARTY_PRIVATE_HTTP=false` is described as SSRF protection, and it controls whether the third-party proxy may forward to local or private HTTP endpoints, with Ollama, LM Studio and vLLM at `http://localhost:11434` or `http://host.docker.internal:11434` given as the cases in mind. So reaching a model on your own machine takes two deliberate unlocks, one for the proxy route and one for the MCP transport, and the same class of restriction is enforced a second time inside `THIRD_PARTY_ROUTES`, which accepts only https and non-private hosts.
The MCP layer adds a human-in-the-loop step: a dialog asks for authorisation before an external MCP tool call executes. Alongside it there is management and status for MCP tools, prompts and resources, and developer log monitoring for tracing calls and errors. `ENABLE_LIVE_WS_PROXY` defaults to true, and when set the api container terminates the WebSocket upgrade on `/api/live` and bridges it to the Gemini bidirectional endpoint, with `LIVE_WS_IDLE_TIMEOUT_MS` at 300000 as the idle limit.
A Robotics model was retired and the notice is dated a month before the shutdown
The migration notice is dated 2026-08-01 and covers the drop of `gemini-robotics-er-1.6-preview`, stating that model was taken out of service on 2026-08-31. The built-in model moved to `gemini-robotics-er-2-preview`, and the whole project defines it in one constant, `ROBOTICS_MODEL`, in `src/constants/modelConfiguration.ts`, which is the right shape for a value that has already changed once.
The operational part of that notice is the reason to read it. Before using a Robotics model, the key in `GEMINI_API_KEY` has to carry an API restriction added in AI Studio, because an unrestricted key returns `403 Forbidden`. A user who arrives with a plain key therefore meets an HTTP status rather than an explanation, and the restriction is the first thing to check when that happens. The notice also recommends `thinking_level` at `medium` by default as a balance of latency and performance, reserving `high` for high-precision spatial tasks, and suggests averaging several queries of the same input in high-precision scenarios to reduce variance.
The runtime configuration section that follows opens with the same prerequisite and then ends partway through its first sentence, so the rest of that subsection is not spelled out here. The `.env.example` file carries the practical half of it: the Robotics endpoint needs the restricted key, and the dedicated `LIVE_GEMINI_API_KEY` exists so a Live API key can be limited separately from the one used for ordinary requests.
Blank price cells are a deliberate result, not a missing feature
The logs and usage pages run in what the project calls a strictly exact mode. A price is shown only when the stored fields are enough to reconstruct the official charge exactly, and when they are not, the cell keeps a dash placeholder. That design explains a support question people usually ask about cost screens: an empty cell can mean a missing field rather than a free request.
The fields are filled in unevenly over time. Newly created chat, text to speech, transcription and some image generation requests record more complete billing metadata than older ones. Plain text conversations get local `TEXT` to `TEXT` modality evidence backfilled, which is why text-only sessions on `gemini-3.8-flash`, `gemini-3.1-pro-preview` and `gemini-3.5-flash-lite` can display a price at all. Historical entries, and anything without exact pricing fields, stay blank.
The same strictness appears in the safety settings. Five filter categories are configurable individually, covering harassment, hate speech, sexually explicit content, dangerous content and jailbreak protection, and each has five levels, where the first two both leave nothing blocked. All five categories default to off, matching the official defaults of the Gemini 2.5 and 3 series. The developer log panel behind these numbers covers API call monitoring and token usage statistics, and the data management layer handles full chat import and export, session grouping, and session search across titles and content.
Editorial conclusion
This is a substantial single-owner project with an unusually honest security posture written into its own defaults: MCP transports off, private-network forwarding off, the API port exposed rather than published, and a plain statement that the default configuration is not an internet-facing gateway. Two things decide whether it fits. First, the Node window, because engine-strict means a wrong runtime fails the install instead of warning. Second, where your keys live, because the same build accepts browser keys, .env.local values and a JSON blob of server-side routes, and SERVER_KEY_PRIORITY decides which one the request actually uses. Check both before deploying, and remember the price panel blanks out by design whenever a stored record cannot reconstruct the official cost exactly.
Frequently asked questions
What does AMC-WebUI do, and does it need a backend?
It is a local-first React 18 console for Google Gemini, with chat data kept in browser IndexedDB by default and an additional OpenAI-compatible chat mode. A backend is optional: it runs as a Vite project locally, or as a web plus api pair in Docker where the api container provides the Gemini proxy, third-party forwarding, the Live API WebSocket proxy and the MCP bridge.
Which Node versions can AMC-WebUI be installed on?
Node 24 to 26. The package manifest declares engines >=24 <27 and engine-strict is enabled, so Node 27 and above, or 23 and below, fails the install rather than warning. Node 26 is the recommended version, 24 is the minimum, and the container images are built on node:24-slim.
Does the AMC-WebUI Docker setup need authentication?
Not by default: ACCESS_PASSWORD, SERVER_ACCESS_TOKEN and ALLOWED_ORIGINS all ship empty, and the documentation positions the default BYOK configuration as a trusted self-hosted deployment that is not sufficient as a public multi-user gateway. Exposing it means adding authentication, quotas and rate limits, abuse protection, auditing and tenant isolation yourself.
Can AMC-WebUI use an OpenAI-compatible API for chat?
Yes, in a separate lane with its own key, base URL and model list, sending requests to POST {Base URL}/chat/completions. It does not overwrite the Gemini configuration and it does not use the Gemini native toolchain, so Gemini-only capabilities such as Thinking, the Live API, Deep Search, code execution and image generation stay in native mode.
Why do MCP transports and local model endpoints stay disabled in AMC-WebUI?
ENABLE_MCP_STDIO and ENABLE_MCP_PRIVATE_HTTP both default to false, and ENABLE_THIRD_PARTY_PRIVATE_HTTP defaults to false as SSRF protection for forwarding to local endpoints such as Ollama, LM Studio or vLLM. The instruction is to enable them only for trusted self-hosted deployments, and THIRD_PARTY_ROUTES separately accepts only https and non-private hosts.
Why does AMC-WebUI return 403 Forbidden when using a Robotics model?
The key in GEMINI_API_KEY has to carry an API restriction added in AI Studio, and an unrestricted key is rejected with that status. Support for gemini-robotics-er-1.6-preview was dropped and the built-in model moved to gemini-robotics-er-2-preview, defined by the ROBOTICS_MODEL constant in src/constants/modelConfiguration.ts.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/yeahhe365-amc-webui)Star history chart for your README
[](https://hysenlabs.com/projects/yeahhe365-amc-webui)Was this useful?