eMuleBB User Guide¶
eMule broadband edition
Classic eMule control, modern broadband operation.
eMuleBB is for power users who want a native Windows eMule client that can run for long sessions, keep large libraries predictable, expose a trusted local REST surface, and still respect stock eD2K/Kad behavior.
Start here if you are setting up a profile, moving an existing eMule install, testing a release package, or wiring eMuleBB into aMuTorrent, Prowlarr, Radarr, or Sonarr.
The eMuleBB Suite¶
This guide covers the eMuleBB Windows client (the 0.7.3 eD2K/Kad desktop
app; the 0.7.x feature line closes at 0.7.3, with MFC modernization continuing
in the 0.8.x line). It is one product in the broader eMuleBB Suite: the
forward multiplatform core emulebb-rust, the BitTorrent companion
qBittorrentBB, and the forward cross-network controller + installer
TrackMuleBB (which replaces aMuTorrent in the 0.8.* program — aMuTorrent
stays maintained until 0.7.3 final — and drives any /api/v1 core by advertised
capability). For the suite as a whole — roadmap, the three-network bundle
(eD2K / BitTorrent / Usenet), and install/Docker delivery — see the
Suite Roadmap,
Suite Bundle & Installer, and
Suite Docker Delivery.
Start Here¶
Install Fast Path¶
- Full suite one-liner:
run the current stable
0.7.3PowerShell bootstrapper directly from GitHub Releases when you want eMuleBB plus aMuTorrent, Prowlarr, Radarr, and Sonarr integration. - Manual standalone ZIP:
download the current stable
0.7.3eMuleBB ZIP, extract it into a new app folder, and startemulebb.exe. - Hyper-V isolated suite runs: prepare clean local Windows guests and run package or suite checks without touching the host's daily eMuleBB profile.
- Running on macOS and Linux: options for using eMuleBB off Windows through a virtual machine, Wine, a Windows-hosted core with a cross-platform controller, or aMule.
Use these guides in order for a first real profile:
- Setup Guide covers install layout, first launch,
existing profiles, isolated
-cprofiles, and release-aware testing. - Product Guide explains what eMuleBB is, what it changes, and how to operate it as a power user.
- Power User Manual teaches eMule from zero through full operation: eD2K, Kad, High ID, queues, credits, parts, sharing, automation, safety, diagnostics, and tuning.
- Network Guide covers eD2K, Kad, ports, bind settings, UPnP, firewall behavior, and WebServer listener basics.
- Downloads And Search covers search quality, categories, transfer actions, disk-space protection, and broadband upload policy.
- Sharing Guide covers shared directories, monitored shares, large libraries, and share-ignore rules.
- Stack Integration Guide covers the eMuleBB plus aMuTorrent plus Arr workflow with field-level setup details.
For public release testing, use the 0.7.3 release notes before downloading or reporting package behavior.
Developer And Release Operator Paths¶
If you are contributing, validating, or preparing a release, start with the workspace and release controls instead of the product manual:
| Role | Start Here |
|---|---|
| Contributor or AI agent | Workspace Policy and Agent Checklist |
| Routine developer | Development Guide |
| Backlog owner | Active Backlog and Backlog Process |
| Release operator | 0.7.3 Release Train Dashboard |
| REST/controller reviewer | REST Contract and Controller Surface Matrix |
Release operators should also use the Execution Plan and Runbook.
Power User Paths¶
Bring Your Existing Profile
Launch with an explicit profile directory, keep temp and incoming paths stable, and verify the profile before enabling controllers.
Existing profile recipeRun Clean Test Builds
Unpack each package into its own app directory, start with
-c <profile>, and keep rollback evidence.
Control It Locally
Use the trusted REST surface for local automation, with explicit bind, API key, firewall, and lifecycle rules.
Controllers and RESTAutomate Media Workflows
Present eMuleBB to Prowlarr, Radarr, and Sonarr through Torznab and qBittorrent-compatible adapter paths.
Stack integration guideAutomation Fast Path¶
eMuleBB's main automation story is local and operator-controlled: the native desktop app owns eD2K/Kad state, while REST, aMuTorrent, qBittorrent-compatible routes, and Torznab routes make that state easier to operate.
| Goal | Start Here |
|---|---|
| Make the first authenticated REST call | REST Quickstart |
| Understand the exact REST contract | REST API Contract |
| Wire aMuTorrent, Prowlarr, Radarr, or Sonarr | Stack Integration Guide |
| Review adapter compatibility | REST Adapter Notes |
First Hour Checklist¶
For a serious profile, do not start with every feature enabled. Prove the desktop app first, then layer automation on top.
| Step | What To Prove | Guide |
|---|---|---|
| Install | App directory and profile directory are intentionally separate. | ZIP install |
| Profile | preferences.ini, temp, incoming, categories, and identity files are where expected. |
Persistence Files |
| Network | TCP, UDP, firewall, UPnP, High ID, and Kad state are understood. | Network |
| Search | A small search returns believable results before heavy automation starts. | Downloads And Search |
| Sharing | Shared roots and monitored shares are deliberate, not accidental broad folders. | Sharing |
| Controllers | REST status reads pass before any mutation or Arr workflow is enabled. | Stack Integration |
Product Guides¶
| Need | Primary Doc |
|---|---|
| Product overview and operating model | reference/GUIDE-EMULEBB |
| Landed behavior matrix and evidence model | reference/RELEASED-BEHAVIOR-SUMMARY |
| Public-readable roadmap themes | reference/ROADMAP-SUMMARY |
| Complete eMule manual from zero to power-user operation | reference/GUIDE-POWER-USERS |
Setup, -c profiles, release package testing |
reference/GUIDE-SETUP |
| Running on macOS or Linux via VM, Wine, or remote control | reference/GUIDE-CROSS-PLATFORM |
| Search, downloads, categories, limits, upload policy | reference/GUIDE-DOWNLOADS-SEARCH |
| Shared directories, monitored shares, large libraries | reference/GUIDE-SHARING |
| eD2K, Kad, bind, ports, UPnP, firewall | reference/GUIDE-NETWORK |
| eMuleBB, aMuTorrent, Prowlarr, Radarr, Sonarr setup recipes | reference/GUIDE-STACK-INTEGRATIONS |
| REST semantics, qBit-compatible/Torznab adapter behavior | reference/GUIDE-CONTROLLERS-REST |
| p2p-overlord eMule agent boundary and source docs | reference/GUIDE-P2P-OVERLORD-EMULE-AGENT |
Preferences and preferences.ini reference |
reference/GUIDE-PREFERENCES |
Runtime .met and .dat file roles |
reference/GUIDE-PERSISTENCE-FILES |
| IP filter setup and troubleshooting | reference/GUIDE-IP-FILTERS |
| Long-path behavior on Windows | reference/GUIDE-LONGPATHS |
| Keyboard and menu workflow | reference/KEYBOARD-SHORTCUTS |
| Tools menu operations | reference/GUIDE-TOOLS-MENU |
| Diagnostic snapshots, dumps, and metadata diagnostics | reference/GUIDE-DIAGNOSTICS |
| Symptom-led diagnostics and support evidence | reference/GUIDE-TROUBLESHOOTING |
| Translation policy and glossary | reference/GUIDE-TRANSLATIONS |
API And Automation¶
REST is the preferred automation surface. The native desktop app remains the authority for live state.
| Need | Primary Doc |
|---|---|
| First authenticated REST calls | rest/REST-API-QUICKSTART |
| Human-readable REST contract | rest/REST-API-CONTRACT |
| Machine-readable OpenAPI contract | rest/REST-API-OPENAPI |
| qBit, Torznab, Arr, and aMuTorrent adapter notes | rest/REST-API-ADAPTERS |
| REST parity inventory | rest/REST-API-PARITY-INVENTORY |
| Controller surface matrix | active/CONTROLLER-SURFACE-MATRIX |
| p2p-overlord claimed-subset contract boundary | reference/GUIDE-P2P-OVERLORD-EMULE-AGENT |
Translations¶
The long-form product docs are English-canonical for now. Do not fork large translated Markdown copies unless there is a review and maintenance owner. Use Translations And Localization for glossary, terminology, screenshot, command, API field, and localized-homepage rules.
The public homepage in repos\emulebb-pages has localized entry pages. Those
pages should link back to this maintained guide set rather than carrying
stale, partial copies of the manuals.
Workspace And Release Docs¶
These docs are for contributors, release operators, and AI agents. They are kept here because this repository is the canonical documentation home, but they are not the best first read for users.
| Need | Primary Doc |
|---|---|
| Workspace policy | WORKSPACE-POLICY |
| Documentation ownership rules | DOCS-POLICY |
| AI contributor checklist | reference/AGENT-CHECKLIST |
| Workspace repository map | reference/WORKSPACE-REPO-MAP |
| Development and validation guide | reference/DEVELOPMENT-GUIDE |
| Active backlog and release dashboard | active/INDEX |
| p2p-overlord product-family integration plan | active/plans/P2P-OVERLORD-PRODUCT-FAMILY-INTEGRATION |
| Ecosystem suite bootstrap planning | active/plans/ECOSYSTEM-SUITE-BOOTSTRAP-PLAN |
| 0.7.3 release-train control document | active/RELEASE-0.7.3 |
| Public 0.7.3 release notes | active/RELEASE-0.7.3-NOTES |
| 0.7.3 stable changelog | active/RELEASE-0.7.3-STABLE-CHANGELOG |
| 0.7.3 release checklist | active/RELEASE-0.7.3-CHECKLIST |
| 0.7.3 release runbook | active/RELEASE-0.7.3-RUNBOOK |
| Backlog process | reference/BACKLOG-PROCESS |
| Backlog item template | reference/BACKLOG-ITEM-TEMPLATE |
| Evidence retention policy | reference/EVIDENCE-RETENTION |
| CI baseline workflow | reference/CI-BASELINE |
| Test tiers runbook | reference/TEST-TIERS |
| Test suite inventory | reference/TEST-INVENTORY |
| Test curation decisions | reference/TEST-CURATION |
| Release branching and packaging | reference/RELEASE-BRANCHING-AND-PACKAGING |
| eD2K ecosystem inventory | reference/ED2K-PROJECT-INVENTORY |
| eD2K forums and sites inventory | reference/ED2K-FORUMS-AND-SITES |
| Dependency status | dependencies/DEP-STATUS |
| Historical-reference rules | HISTORICAL-REFERENCES |
If a status claim outside docs/active/ conflicts with docs/active/, treat
docs/active/ as authoritative for current local backlog and release state.
For GitHub-primary backlog items marked workflow: github, the linked
emulebb/emulebb issue and the public eMuleBB Roadmap org Project #2 are
authoritative for workflow state.
Browser Site¶
This Markdown tree can be rendered with MkDocs Material:
Use python -m mkdocs build --strict for CI-equivalent local validation. The
Material theme emits a current MkDocs 2.0 compatibility notice as a warning, so
set $env:NO_MKDOCS_2_WARNING='1' before strict local builds. The generated
HTML is written to .local/mkdocs-site and deployed to GitHub Pages by
.github/workflows/docs-site.yml on main at
https://emulebb.github.io/emulebb-tooling/.
Notes¶
- Historical branch names such as
stale-v0.72a-experimental-cleanand old branch labels may appear in reference docs as provenance only. - Preserve commit ids and historical branch names where they add provenance,
but do not treat them as current-branch guidance unless
docs/active/explicitly says the work is landed onmain.