Mango

A friendly MongoDB workbench. Browse, edit, query, and shell into any MongoDB — with an AI assistant that understands your schema.

Landing page and docs

---

Run modes

Important

Mango is a privileged database management tool and currently has no built-in user authentication. Run it only on your local machine or inside a trusted private network. Do not expose Mango directly to the public internet; if you need remote access, put it behind an authenticating reverse proxy, TLS, and network allowlisting.

	When to use
Aspire	You're building on .NET Aspire. One line in your AppHost wires Mango to your Mongo container.
Docker	Standalone deployment: dev box, homelab, k8s. One image, env-driven config.
Desktop	Local workbench across multiple Mongo connections. macOS, Windows, Linux — runs offline.

Quick start

Aspire

using Aspire.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
    .WithLifetime(ContainerLifetime.Persistent);

mongo.WithMango();          // ← drops the Mango UI alongside Mongo

builder.Build().Run();

dotnet add package Mango.Aspire.Hosting

WithMango() defaults to standalone mode: the Mongo container's connection string is wired in as the only connection and the connection-manager UI is hidden. Pass standalone: false to expose the full multi-connection workbench. Override the image with image: / tag: parameters.

Docker

docker run --rm -p 127.0.0.1:5180:5180 \
  -e MONGO_URL="mongodb://host.docker.internal:27017/mydb" \
  -e MANGO_MODE=standalone \
  -v mango-data:/data \
  ghcr.io/philbir/mango:latest

Open http://localhost:5180. Drop MANGO_MODE=standalone to enable the full connection manager (you can then add more connections from the UI).

Or with docker compose:

services:
  mongo:
    image: mongo:7
    volumes: ["mongo-data:/data/db"]

  mango:
    image: ghcr.io/philbir/mango:latest
    depends_on: [mongo]
    ports: ["127.0.0.1:5180:5180"]
    environment:
      MONGO_URL: mongodb://mongo:27017/mydb
      MANGO_MODE: standalone
    volumes: ["mango-data:/data"]

volumes:
  mongo-data:
  mango-data:

Desktop

Download the installer for your OS from Releases and run it. The desktop app ships a self-contained server (Bun-compiled sidecar) with no external dependencies.

To build locally:

pnpm install
pnpm compile-server     # builds the sidecar binary (requires Bun)
pnpm tauri:build        # produces a .dmg / .msi / .deb / .AppImage

Configuration

All modes read the same env vars:

Variable	Purpose
MONGO_URL	Mongo connection string. Required in standalone mode.
MONGO_DB	Default database (overrides URI path).
MANGO_MODE	standalone or unset (= multi-connection).
MANGO_DATA_DIR	Where saved JSON state lives (connections.json, ai-settings.json). Defaults: ./.mango/ (dev), /data (Docker), OS app-data (desktop).
MANGO_MASTER_KEY	32-byte AES-256-GCM key (base64 or hex) for encrypting saved connection URIs. Auto-generated per-process if unset. Set this in production so saved state survives restarts.
PORT	Server port. Default 5180.
HOST / MANGO_HOST	Server bind host. Default 127.0.0.1; set explicitly only for trusted private-network access.
MANGO_BASE_PATH	URL prefix when served behind a reverse proxy at a sub-path, e.g. /mongo for https://example.com/mongo/. The proxy must forward the full path (no prefix stripping); the bare prefix redirects to /mongo/. Unset = served at /.
MANGO_CORS_ORIGINS	Comma-separated extra browser origins allowed to call the API. Defaults include the Vite dev origin.
MANGO_MONGO_MAX_TIME_MS	MongoDB query/command timeout in milliseconds for supported operations, including console reads. Default 60000 (60 seconds); increase for longer queries.
MANGO_CONSOLE_TIMEOUT_MS	Synchronous JavaScript execution limit in the console (prevents infinite loops), separate from MongoDB query time. Default 1000 (1 second).

Each user can also set Query timeout (in seconds) in the Settings menu for document, console, and shell queries. This overrides the server default for that user's requests (1 second to 24 hours); web preferences last for the browser session, while desktop preferences persist in app data. | MANGO_DISABLE_JS_CONSOLE | Set to true to disable the JavaScript console route. |

AI assistant

Variable	Purpose
AI_PROVIDER	openai (any OpenAI-compatible endpoint), copilot, claude-code, or codex.
AI_MODEL	e.g. gpt-4o-mini, claude-sonnet-4.5.
AI_API_KEY	Provider key. OpenAI / GitHub Models / Azure / Ollama.
AI_BASE_URL	OpenAI provider only — point at GitHub Models, Azure, Ollama, etc.
GITHUB_TOKEN	Copilot provider — falls back to logged-in Copilot CLI session if unset.
MANGO_COPILOT_CLI	Optional full path to the Copilot CLI when it is not on PATH (for example ~/.npm-global/bin/copilot). You can also set this in the UI.
MANGO_CLAUDE_CLI	Optional full path to the Claude Code CLI when it is not on PATH (for example ~/.claude/local/claude). You can also set this in the UI.
MANGO_CODEX_CLI	Optional full path to the Codex CLI. Needs a current build (with codex app-server); on macOS Mango falls back to the one bundled in the ChatGPT app. You can also set this in the UI.

You can also configure the assistant from the UI (Settings menu); it'll be persisted (encrypted) in ai-settings.json under MANGO_DATA_DIR.

Development

Prerequisites

• Node.js 22+ with Corepack enabled for pnpm (corepack enable).
• Bun on PATH for pnpm compile-server (curl -fsSL https://bun.sh/install | bash or brew install oven-sh/bun/bun).
• Rust via rustup for Tauri desktop development and packaging (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh).
• Platform WebView/build tools required by Tauri. On macOS this usually means Xcode Command Line Tools; Windows and Linux need the normal Tauri prerequisites for WebView2/WebKitGTK.

pnpm compile-server auto-detects the sidecar target from Rust when available, then falls back to Node's platform/architecture info. You can also pass a target explicitly, for example pnpm compile-server aarch64-apple-darwin.

pnpm install
pnpm dev                # server (5180) + Vite (5173) concurrently
pnpm test               # vitest (server)
pnpm --filter @mango/ui typecheck
pnpm docs:dev           # landing page + docs site
pnpm docs:build         # static GitHub Pages build

The server is ESM Node 22 + Hono + the official mongodb driver. State (connections + AI settings) is persisted as plain JSON files under MANGO_DATA_DIR, with sensitive fields encrypted via AES-256-GCM. The UI is React 19 + Vite + Tailwind + Monaco. The desktop shell is Tauri 2.

See CLAUDE.md for the architecture overview.

Roadmap

See docs/ROADMAP.md. Headlines:

• Phase 1 — Connection manager, AES-GCM encryption, AI assistant, Aspire integration, standalone mode ✅
• Phase 2 — Distribution: Docker / NuGet / Tauri desktop builds ✅ · code signing + auto-update next
• Phase 3 — Mongo auth: OIDC (MONGODB-OIDC), X.509, AWS IAM
• Phase 4 — Index manager, import/export (JSONL/CSV), saved commands (Git provider sync), aggregation builder

License

MIT