Mongozel

MongoDB client for the web. Query your data directly from your browser. You can host it locally, or anywhere else, for you and your team.

Built with Nuxt 4, Vue 3, Nuxt UI 4, and Tailwind CSS 4. Connections are stored in your browser and MongoDB is reached server-side, so it also works for databases that are only reachable from the host Mongozel runs on.

Installation & Usage

Install globally

The easiest way to use Mongozel:

# Install globally
npm install -g mongozel

# Start the server (http://localhost:3000)
mongozel

# Start on a custom port
mongozel --port 8080

# Protect the instance behind a login page
mongozel --password change-me

Using the Docker image

Fastest way to try Mongozel with nothing installed but Docker: clone the repo and run the compose profile that ships a MongoDB to play with — see Using docker compose below, then connect to mongodb://mongodb:27017 from the UI.

Already have a MongoDB? Run the image directly:

docker run -d --name mongozel -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  --env MONGOZEL_PASSWORD=change-me \
  ghcr.io/benalidjamel/mongozel

Inside the container, localhost is the container itself. To reach a MongoDB running on your machine — or one published from another container with -p 27017:27017 — connect from the UI to:

mongodb://host.docker.internal:27017

Docker Desktop (macOS, Windows) resolves that name out of the box; the --add-host flag above makes it work on Linux too. To reach another container without published ports, put both on the same Docker network and use its container name as the host instead.

Using docker compose

MONGOZEL_PASSWORD=change-me docker compose up -d --build

To also start a local MongoDB to play with, enable the with-mongodb profile and connect to mongodb://mongodb:27017 from the UI (the driver runs inside the Mongozel container, so the compose service name resolves):

MONGOZEL_PASSWORD=change-me docker compose --profile with-mongodb up -d --build

Configuration

Everything is configured through environment variables (the CLI flags above are shortcuts for them):

| Variable | Default | Meaning | | --- | --- | --- | | MONGOZEL_PASSWORD | (empty) | When set, the whole app sits behind a login page; sessions last 7 days. When empty, there is no authentication. | | MONGOZEL_READONLY | (empty) | When set to any non-empty value, the server rejects every write operation (document inserts, updates, deletes; index creates and drops) with 403. Reads, aggregations, and exports keep working. | | PORT / NITRO_PORT | 3000 | Port the server listens on. | | HOST / NITRO_HOST | (all interfaces) | Address the server binds to. |

Security notes

• Set MONGOZEL_PASSWORD for anything beyond localhost. Without it, anyone who can reach the port can proxy through Mongozel to any MongoDB the host can reach.
• Terminate TLS in front of Mongozel (Caddy, nginx, Traefik) when exposing it beyond your machine — the login password and connection strings travel in request bodies.
• Connection strings are kept in your browser's storage and sent in POST bodies only; the server stores nothing.
• GET /api/health is unauthenticated and suits container health checks and reverse-proxy probes.
• Changing MONGOZEL_PASSWORD invalidates all existing sessions.
• Found a vulnerability? Please report it privately — see SECURITY.md.

Local development

Requires Node.js 22.19+ / 24.11+ (CI and Docker run 24):

npm install
npm run dev    # http://localhost:3000
npm test       # unit tests only — the fast inner loop
npm run check  # typecheck + unit tests + schema-boundary guard

For a throwaway MongoDB to point the app at, run one and connect to mongodb://localhost:27017 from the UI:

docker run -p 27017:27017 mongo

(The compose with-mongodb profile above only serves the containerized app — its MongoDB has no host port mapping, so a dev server running on the host cannot reach it.)

Contributing

CONTRIBUTING.md maps the codebase, explains the architecture rules (the zod wire contract, defineMongoHandler, the client API surface, the URI-secrecy invariant), and describes the verification gate and testing policy. Start there before opening a pull request.

Releasing

Releases are cut from the Publish GitHub Actions workflow (manual dispatch, pick a patch/minor/major bump). It runs the checks, bumps and tags the version, publishes mongozel to npm, and pushes the Docker image to GHCR as :latest and :<version>. It needs a repository secret NPM_TOKEN (npm automation token); GHCR authentication is built in.

To dry-run the npm package locally:

npm run build
npm run package:npm   # assembles dist-npm/
cd dist-npm && npm pack --dry-run

License

MIT