Zimi Server

CI Tests Lighthouse Accessibility WCAG 2.1 AA i18n Docker Pulls PyPI License: MIT

A modern experience for your ZIM files.

Kiwix packages the world's knowledge into ZIM files. Zimi makes them feel like the real internet with a rich web UI, fast JSON API, and an MCP server for AI agents. Everything works offline, in your language.

What is Zimi?

• The offline internet. Whole sites, cross-ZIM links, real search, a browser that feels like one.
• Search that hits everything. One query, every source, 100M+ articles, the right answer on top.
• A real library. 1,000+ archives one click away, auto-updating, with collections and bookmarks.
• Multilingual. Any article in any language it has. Ten UI languages built in.
• Fresh daily. Picture of the Day, On This Day, a word, a quote, a comic, a live sky. Computed locally, forever.
• Your own network. Your machines find each other and pass ZIMs around at LAN speed.
• A good citizen. Downloads come over BitTorrent and seed back. One switch makes you a mirror.
• Manageable. Accounts and per-ZIM access, wide open or sign-in only. A health endpoint and an activity log when you need them.
• Accessible. Keyboard, screen reader, high contrast. Built in, not bolted on.
• A ZIM creator (beta). A page, a site, a video or playlist, your bookmarks or a folder becomes a ZIM.
• For humans and machines. Web UI, JSON API, MCP server for agents.
• Anywhere. Docker, pip, a native macOS app, or your phone as a PWA.
• Improving. Regular updates, shaped by what people ask for. Just ask.

Screenshots

Homepage	Search Results

Language Switching	Catalog

Sharing	Make a ZIM

Languages

Not an afterthought. Language is deeply integrated into every aspect of Zimi so you can focus on your content and feel at home. Enjoy filtered lists, labeled sources, RTL support and no rock left unturned.

• 10 languages. English, French, German, Spanish, Portuguese, Russian, Chinese, Arabic, Hindi, Hebrew.

Something not right? Open an issue. Found a security problem? See SECURITY.md and report it privately.

Sharing

Three switches in Server Settings control all of it:

• BitTorrent (on by default). Downloads arrive via the Kiwix swarm and seed back, capped at a ratio you choose. 0 means never seed. The engine is in-process libtorrent: the desktop apps and Docker image bundle it, and pip install zimi pulls it automatically wherever a prebuilt wheel exists (CPython 3.9–3.13 on Linux, macOS, and Windows). If there's no wheel for your interpreter, Python 3.14+ has none yet, Zimi quietly falls back to plain HTTP and prints the one-line fix; pip install zimi[bt] forces the attempt. UPnP asks your router to open the port, and the settings panel shows whether it worked. Concurrent downloads and the peer-connection limit are tunable in the same panel.
• Nearby (off by default). Flip it on and Zimi devices on your network find each other; a green pill on a catalog card means a neighbor already has that ZIM. Transfers stay on your LAN, never the internet.
• Mirror (off). Lifts the seeding cap, for people who want to run a long-term Kiwix mirror.

Seeding needs no router setup: Zimi opens the BitTorrent port automatically (UPnP) and the settings show whether peers can reach you, with a retry when they can't. DHT is on too, so magnet links and trackerless swarms just work.

Make your own ZIMs

The library isn't only what you download. Zimi packages new ZIMs from the + button in the web app or zimi create on the command line. Every mode previews what you'll get before anything runs, streams a live log while it works, and the result joins your library the moment it finishes.

• A folder: HTML, Markdown (rendered by a built-in converter), and PDFs become a browsable ZIM, cross-file links intact. Command line only (zimi create ./folder), the web app deliberately doesn't read the server's filesystem.
• A web page: one URL, or a list of up to twenty, captured with its images, styles, and fonts.
• A whole site: a bounded, polite, same-origin crawl: page, depth, and byte budgets, robots.txt honored, and Ctrl-C still writes a valid ZIM of everything captured so far.
• Videos: a playlist or channel becomes an offline video ZIM with subtitles, powered by yt-dlp.
• A web archive: zimi import converts WARC and WACZ files from ArchiveBox, Webrecorder, browsertrix, or HTTrack. Powered by a managed warc2zim sidecar (needs Python 3.14 and libmagic on the machine, the Docker image ships both).

Three capture engines trade speed for fidelity: Fast (no browser required), Rendered (a real headless Chromium draws pages that build themselves in JavaScript), and Alive (records the browser session so the page's own JavaScript still runs offline, menus, galleries, videos). Rendered and Alive can block ads and trackers at capture time from a published blocklist.

Every created ZIM carries honest provenance (which Zimi, which tools, how many pages and bytes, what was blocked) as openZIM-spec metadata validated with zimcheck. Right-click any library card → About this ZIM to see it.

Install

macOS

brew tap epheterson/zimi && brew install --cask zimi

Or download from GitHub Releases.

Linux

sudo snap install zimi

Or grab the AppImage.

Docker

docker run --network host -v ./zims:/zims -v ./zimi-config:/config epheterson/zimi

/zims is where ZIM files live. /config persists cache, indexes, and settings. Open http://localhost:8899.

--network host is recommended so LAN peer discovery (mDNS) and BitTorrent seeding work out of the box. If you can't use host networking, see "Bridge mode" below.

services:
  zimi:
    image: epheterson/zimi
    container_name: zimi
    restart: unless-stopped
    network_mode: host           # mDNS + BT seeding work without port plumbing
    volumes:
      - ./zims:/zims             # ZIM files go here
      - ./zimi-config:/config    # cache, indexes, settings

services:
  zimi:
    image: epheterson/zimi
    container_name: zimi
    restart: unless-stopped
    ports:
      - "8899:8899"
      - "6881:6881/tcp"          # BitTorrent (TCP)
      - "6881:6881/udp"          # BitTorrent (UDP / DHT)
    volumes:
      - ./zims:/zims
      - ./zimi-config:/config

Python

pip install zimi
ZIM_DIR=./zims zimi serve --port 8899

Environment Variables

Most people set nothing: every setting below has a sensible default or lives in the UI.

Self-hosting & operations

Zimi runs seriously with zero ceremony: zimi serve in or beside a folder of ZIMs discovers it and keeps its state in a .zimi folder next to the content. A USB stick is a valid deployment. When you want more control:

• One config file. zimi.json holds paths, auth, sharing, and serving settings; zimi config prints every effective value and exactly where it came from, flag, environment, file, discovery, or default.

• Backup and restore. zimi backup writes settings, bookmarks, collections, and user data to one file; zimi restore brings a fresh install back from it.

• Provable offline. ZIMI_OFFLINE=1 is a real air-gap switch, verified by a test that records every outbound socket.

• Monitoring. GET /health for liveness, GET /metrics in Prometheus exposition format for the rest.

• Reference manifests. deploy/ carries docker-compose and Kubernetes examples, and scripts/make-airgap-bundle.sh builds a wheels-only installer for machines that will never see the internet.

• Update awareness. Manage shows the current version and checks for releases on demand, Latest or Beta channel, with an optional hold-back delay.

• Secure first-run. Until an admin password is set, the machine running Zimi can set one directly; any other device needs a one-time setup key Zimi prints to its log on first start. So a LAN, container, or tailnet neighbor can never claim the admin account before you do. Set ZIMI_MANAGE_PASSWORD to skip the bootstrap entirely.

Single sign-on through Cloudflare Access is available for tunnel deployments (experimental), see docs/deployment-networking.md.

Documentation

Each guide is structured as How it works / Configure / Troubleshoot. Start at the feature guide index.

• Reading, search and ranking, the reader and Reader View, bookmarks and history, word lookup, cross-language articles, PDFs, offline/PWA, accessibility, the almanac.
• Making ZIMs, zimi create for a folder, page, --site crawl or video; the four engines and what each trades; bookmarks as a standalone ZIM; zimi import for WARC/WACZ.
• Getting & sharing, catalog and downloads, folders as categories, same-flavor auto-update, BitTorrent seeding, Nearby (mDNS LAN), the /dl/ peer transport.
• Access, public-access modes, named accounts, per-ZIM allowlists, the creator role, the first-run bootstrap, Cloudflare Access SSO.
• Operations, zimi config + config file, backup/restore, air-gap, /metrics, /health, update channels, deploy manifests.
• API & MCP, the MCP server and tools, the stable JSON API, /openapi.json, /chunks.

API

Examples

# Search across all sources
curl "http://localhost:8899/search?q=python+asyncio&limit=5"

# Search in French only
curl "http://localhost:8899/search?q=eau&lang=fr&limit=5"

# Find all languages for an article
curl "http://localhost:8899/article-languages?zim=wikipedia&path=A/Water"

# Read an article
curl "http://localhost:8899/read?zim=wikipedia&path=A/Water_purification"

MCP Server

Zimi includes an MCP server for AI agents.

{
  "mcpServers": {
    "zimi": {
      "command": "python3",
      "args": ["-m", "zimi.mcp_server"],
      "env": { "ZIM_DIR": "/path/to/zims" }
    }
  }
}

For Docker on a remote host:

{
  "mcpServers": {
    "zimi": {
      "command": "ssh",
      "args": ["your-server", "docker", "exec", "-i", "zimi", "python3", "-m", "zimi.mcp_server"]
    }
  }
}

Tools: search (with lang filter), read, get_chunks, suggest, list_sources, random, article_languages, read_with_links, deep_search, list_collections, manage_collection, manage_favorites

Integrations

• SearXNG: route queries through Zimi from a self-hosted SearXNG metasearch instance.
• OpenWebUI / generic AI: wire the MCP server into any AI client for offline research.

Long-requested, shipped here

Every issue filed against Zimi has been answered, #33 country holiday colors, #34 new-ZIM badges and recency filters, #36 Tailscale-friendly management, #37 library organization, #38 fragment links, #44–46 access modes and per-user data, #48–51 almanac, anchor, flavor, and Raspberry Pi fixes, #65 in-article bookmarks, #76 update awareness. And features the wider ZIM ecosystem has been asking for, available today:

• Spelling suggestions: "did you mean?" on weak searches, fully offline (libzim #731)
• Read-aloud: text-to-speech in the reader via the offline Web Speech API (kiwix-js #166)
• Reader View: a clean, adjustable reading mode (themes, fonts, text size) for any article
• Word lookup: tap a word in any article, get the dictionary entry from your own library
• Resumable downloads: an interrupted ZIM download picks up where it left off, and updates reuse the unchanged pieces of the old file instead of re-downloading everything
• User accounts: named logins with per-ZIM access lists, so one server can serve the whole house (or classroom)
• A native Windows app: with the same auto-update channel as macOS
• Give back: seed your downloads to the Kiwix swarm at a ratio you choose, or flip one switch and be a full mirror
• Grab the file: a download button for any ZIM you're sharing on your network
• Real article counts: articles, not raw entry counts, on library cards

Contributing

See CONTRIBUTING.md.

License

MIT. Desktop and Docker builds bundle libtorrent-rasterbar (BSD-3-Clause) for BitTorrent transfers, see THIRD_PARTY_NOTICES.md.

Built with ❤️ in California by @epheterson and Claude Code.