Ember Guide

About Ember

Ember is not a fork or reskin of eMule. It is a complete reimplementation of the eMule protocol stack in safe Rust, paired with a lightweight Tauri + Svelte shell. It speaks the same KAD wire protocol as eMule 0.50a and compatible clients (aMule, eMule Xtreme, etc.), participates in the same network, finds the same sources, and respects the same credit system. KAD is joined automatically at startup; ED2K servers are yours to choose, and on first launch Ember can seed a community server.met from emule-security.org.

Ember also runs a network of its own. The Ember Network is an encrypted overlay with no servers and no central directory: Ember nodes find each other directly, publish the files they share, and look up sources for a download over their own DHT. It is on by default and runs alongside KAD and eD2K, so you keep the whole eMule network as well.

On top of that, EPX (Ember Peer Exchange) speeds up source discovery between Ember peers on the ordinary eMule wire, and an Ember-exclusive Friends system adds end-to-end encrypted chat, Noise-secured sessions, and privacy-preserving Friend Codes — all invisible to non-Ember clients.

Installation & updates

Supported Operating Systems

Windows 10 and Windows 11. On Linux, x86-64 distributions with glibc 2.35 or newer (Ubuntu 22.04 and later, Debian 12 and later, and their derivatives), as a .deb or an AppImage. The AppImage needs FUSE 2 to start — libfuse2 on Ubuntu 22.04, libfuse2t64 on Ubuntu 24.04 and Debian 13 — so on those the .deb is the simpler choice.

Requirements

No external runtimes needed. No Java, no .NET, no browser engine download. Ember ships everything it needs in a single installer.

Updates

Ember updates itself. Every release is signed, and Ember checks the signature of both the release manifest and the package before installing anything. Each build updates with the format it was installed from, so a .deb install updates through dpkg and an AppImage replaces itself in place.

With Silent updates switched on in Settings > About, Ember installs a new version by itself while nobody is using it, and reopens the way you left it. This works with the Windows installer and the AppImage. The .deb and MSI packages need your password or administrator approval to install an update, so there Ember tells you an update is ready and you install it with one click.

Getting Started

1. Install
   Download the latest release from the Releases page and run the installer. On Linux, install the .deb with your package manager, or mark the AppImage executable and run it.
2. Setup Wizard
   On first launch, the Setup Wizard walks you through essential settings — an optional import from an existing eMule install, nickname, download folder, ports, speed limits, and theme.
3. Connect
   KAD connects on its own at every launch, so there is nothing to press; you can still disconnect for the current session from the KAD Network page. The Ember Network needs no connect step either — it is on by default and finds its first peers through KAD. ED2K servers stay opt-in: connect from the ED2K Servers page, or enable Auto-connect to server in Settings > Network so Ember rejoins your last one on launch. A community server.met list can be downloaded from emule-security.org on first run.
4. Share & Download
   Add folders to your library, search with the All networks / Server only / KAD only / Ember only methods, open ed2k:// links, and start downloading. Right-click a result to look for related files or to look the file up on a web service. Ember handles multi-source transfers, queue management, and source discovery automatically.
5. Add Friends (optional)
   Open the Friends page, share your Friend Code, and add theirs. Adding somebody already gives them priority in your upload queue; once the two of you are mutual and online you also get end-to-end encrypted chat, remote file browsing, and friends-only shares. See Friends.
6. Join a Channel (optional)
   Open the Channels page, pick a Channel username, then create a room or paste an invite. Discover lists public rooms other people have published. See Channels.

Features

Networking

• Ember Network — Ember’s own encrypted, server-less overlay for peer discovery, keyword search, publishing, and source lookup. Always on, joins automatically, and runs alongside KAD and eD2K. See the Ember Network section.
• KAD Network — The decentralized KAD DHT for peer discovery, keyword search, publishing, firewall checks, and buddy relay. Bootstraps at startup with no setting to configure; the KAD Network page can disconnect it for the current session. If KAD will not connect, Settings > Network can fetch fresh nodes.dat bootstrap contacts from emule-security.org.
• ED2K Servers & Peer Exchange — Manage servers on the ED2K Servers page, download a community server.met from emule-security.org, and optionally turn on Auto-connect to server (last server, else eMule Sunrise). Once connected, peer exchange helps find sources.
• EPX Source Exchange — Ember peers share source lists with each other for faster downloads. Non-Ember clients are unaffected.
• NAT Traversal — UPnP automatic port mapping, firewall detection, KAD buddy relay for LowID peers, and EPX peer-relay (ERAT) for LowID↔LowID paths when attestations allow.
• STUN Port Keep-Alive — Periodic STUN plus a TCP hold from your listen port keeps NAT mappings alive and advertises the discovered public TCP/UDP ports for High ID. Designed for CGNAT and full-cone NAT when UPnP is unavailable; auto-suspends on symmetric or unstable remapping.
• Protocol Obfuscation — RC4-based TCP and UDP header encryption to help with ISP throttling.
• Deep Links — Opens ed2k:// URIs and .emulecollection files from the OS (including while Ember is already running). Incoming links require confirm / review before opening, and pending links can be reviewed later.

Transfers

• Multi-Source Downloads — Download from multiple peers simultaneously with part-level hash verification, automatic source rotation, and queue management.
• Transfer Monitoring — Real-time progress bars, per-source detail drawers, upload tracking, health indicators, and archive recovery. The Sources column reads the way eMule’s does, counting peers holding a place in a remote queue and showing how many are actually transferring in parentheses.
• Find More Sources — Ask every connected network for more sources for one download — KAD, the Ember DHT, the connected eD2K server over TCP, and the rest of the server list over UDP. Each leg answers on its own schedule and what it finds goes straight into the transfer; legs with nowhere to send the question are reported rather than waited on.
• Bulk Transfer Actions — Tick rows (or use the header checkbox) to pause, resume, stop or cancel many downloads at once, or use the Pause / Resume / Stop / Cancel All commands in the toolbar's More menu. Completed and failed rows can be selected the same way and removed from the list together; the files themselves are kept.
• Upload Speed Sense (USS) — Optionally adjusts upload speed from network latency to reduce congestion (requires an upload speed limit).
• AICH — Advanced Intelligent Corruption Handling for part-level hash verification and recovery.

Search & Library

• Advanced Search — All networks, KAD only, Server only, and Ember only keyword search with multi-tab results plus type, size, source, and extension filters. All networks runs every network that is up, so Ember results arrive alongside KAD and server hits, de-duplicated into one list.
• Related Files — Right-click a search result, a transfer or a shared file to look for the rest of what it belongs to. eMule’s version asks the connected server and is unavailable unless that server advertises support, which most do not; Ember keeps that request as one signal and also reads the season and episode marker, disc or part marker, year and title out of the file’s own name, so the search runs on every network with no server support. The tab is named after what it went looking for.
• Web Services — eMule’s right-click > Web services: open a site with a file’s details substituted in, most usefully one that reports how many complete sources the network has seen. All six eMule placeholders are supported and an existing webservices.dat can be imported. An availability lookup ships configured; nothing is contacted until you click one, adding a site asks for confirmation, and the list is editable in Settings > Web services.
• Spam Detection — Built-in spam detection with Relaxed, Balanced (the default) and Aggressive profiles, each setting how high a score must be to count as spam, and automatic result hiding.
• Library Management — Virtual-scrolling tables that handle thousands of files. Sort, filter, bulk-edit priorities, scan for missing files, copy all eD2K links for the current view, and create collections.
• Copy eD2K Links from Search — Copy the link for one result, for every ticked result, or for the whole result list at once, from the context menu, the selection toolbar, or Ctrl+C.
• In-App Media Player — Play supported audio and video from the Library detail drawer, with Open Externally still available.
• Comments & Ratings — Add metadata to your shared files for other peers to see.

Social

• Ember Friends — Ember-exclusive friend system powered by a rendezvous server. Share a Friend Code, exchange mutual requests, then enjoy real-time online status, remote file browsing, friends-only shares, file offers, priority upload slots, durable offline chat, and end-to-end encrypted messaging. See the Friends section for details.
• E2E Friend Chat — Mutual-friend messages use static X25519 ECDH + AEAD end-to-end encryption after session setup. A lock icon in the chat window and on online mutual friends’ cards marks it; plaintext fallbacks are rejected. Conversation history is encrypted in the local database, and outbound messages queue until the friend is reachable again. Being a static exchange, it provides no forward secrecy and covers message bodies only — see E2E Encryption.
• Noise-Secured Friend Sessions — Friend connections use Noise IK secure streams with Ed25519 proof-of-possession before chat, browse, offers, and verified friend privileges unlock. Friend file transfers can also run over the same secure path when ordinary HighID/callback routes are unavailable.
• Channels Beta — Group rooms carried over the Ember Network itself. Create a public room anyone can find or a private one that needs an invite, moderate it with bans, moderators, owner-only invites and slow mode, edit and react to messages, and send a file to one member at a time — encrypted to that member, not to the room. Nobody publishes their IP address to the room. See the Channels section for details.
• Credits & SecIdent — RSA-based Secure Identification prevents credit theft. Upload priority follows the standard credit ratio formula.

Security

• Signed Anti-Rollback Updates — In-app updates are cryptographically signed and gated by security epochs, so installs only advance when the signed epoch allows it.
• Safer File Opens — Deep links require confirm / review; folders dropped on the Library are shared directly, while dropping files, your user folder or a large batch asks first, and sharing a whole parent folder or drive needs a native confirmation; media and upload paths pin approved handles to avoid path-swap races.
• Confirmed External Links — A link in a room or a message is opened only after a native system confirmation, showing the destination host, and only after the host is checked: anything that is or resolves to a loopback, private or link-local address is refused, so a link cannot reach your router’s admin page or a cloud metadata endpoint. Web services collect the same confirmation once, when a site is added to the list.
• Security Page — A dedicated page for IP filter management: download the default list, import a file, fetch from an HTTPS URL, enable or disable filtering, add and remove custom ranges, and review how many times each range has actually blocked something.
• IP Filtering — Download the default ipfilter.zip with one click, import an ipfilter.dat / ipfilter.zip file, or fetch one from an HTTPS URL; the list is updated when you ask, not on a schedule. Incoming connection filtering is off by default because VPN IP ranges commonly appear in ipfilter.dat hosting blocks, silently blocking legitimate peers. Outbound filtering remains active regardless of this setting.
• Anti-Leech Filter — Reject incoming connections from known leech client patterns (customizable regex list in Settings).
• Private IP Blocking — Prevents connections to reserved IP ranges.
• Content Security Policy — Strict CSP headers in the Tauri webview.
• Path Traversal Protection — Sanitized file paths prevent directory escape attacks.

User Experience

• First-Time Setup Wizard — Guided configuration on first launch: an optional import from an existing eMule install, nickname, download folder, ports, speed limits, and theme, plus a summary of the networks Ember joins on its own.
• Clean UI — Modern, responsive interface with real-time transfer monitoring and inline search filtering.
• Close to System Tray — Choose what the title-bar close button does — ask each time, minimize to tray, or exit. The tray icon stays available either way, so you can reopen Ember from there. On a Linux desktop with nothing to show the icon, such as stock GNOME without the AppIndicator extension, closing to the tray minimizes the window instead.
• Keyboard Shortcuts — Press ? for a shortcut cheat sheet, Alt+1–9 then Alt+0 to jump straight to the first ten sidebar pages, and Ctrl+, to open Settings.
• Backup & Restore — Settings > Backup saves your whole profile to a single passphrase-encrypted .emberbackup file: identity and SecIdent keys, upload credits, settings, shared-folder list, known files, friends, chat history, transfer list, server and Kad contacts, IP filter, and learned spam data. The files you share and part-finished downloads are not included, so a backup stays small. Encryption is mandatory because the archive contains your private keys, and a lost passphrase cannot be recovered. Your identity keys are unwrapped from this machine’s at-rest protection (Windows DPAPI, or on Linux a key tied to the machine and your user) into the encrypted archive and re-wrapped for whichever account restores them, so a restore on a new machine keeps your user hash, credits and friendships instead of silently rotating them. Restores are prepared immediately and applied while Ember next starts (the files being replaced are in use while it runs); the replaced originals are kept in a pre-restore-<timestamp> folder beside them, and a pending restore can be discarded from the same screen before it is applied. A restore that has sat waiting for more than a month is dropped rather than applied on top of the profile you have been using since; the backup file is untouched, so you can simply import it again. After restoring onto a different machine, the restored shared and download folders are approved automatically, so put the files back at the same paths; and if the backup carried the database without chat-history.key, existing chat history stays sealed.
• Statistics — Session and cumulative transfer statistics, connection uptime, network health indicators, and a peer reputation snapshot.
• Automatic Updates — Ember checks for new versions on the schedule you choose (hourly, daily, weekly or monthly; daily by default), including while it stays open, and installs cryptographically signed, anti-rollback updates in-app with one click. You can also check manually under Settings > About.
• Silent Updates — An optional switch in Settings > About for anyone who leaves Ember running. A new version downloads and verifies in the background, then waits until nothing is transferring and nobody has touched Ember for ten minutes. A one-minute warning appears as a dialog, a desktop notification and a Cancel update entry on the tray icon, and Not now puts it off for a day. Ember then updates and comes back as you left it: hidden in the tray or where the window was, connected to the same eD2K server, on the same page, with your search tabs, and with the peers waiting in your upload queue still in line. If an update ever fails to install, Ember reopens on the version you had and never retries that version silently.
• Languages — Full UI localization for English, Spanish, French, Brazilian Portuguese, German, Simplified Chinese, Italian, Russian, and Traditional Chinese, with a Settings language picker and system-language detection.
• GeoIP — Country identification for connected peers via the bundled DB-IP Country Lite database (MMDB format).

Ember Network

The Ember Network is Ember’s own peer-to-peer overlay: a second network that Ember nodes run between themselves, in parallel with KAD and eD2K. Nodes find each other directly, publish the files they share, and look up sources for a download over their own DHT. There is no directory server, no tracker, and no shipped seed list, and every frame between nodes travels inside an encrypted session.

It is always on and joins on its own — there is no Connect button and no switch to turn it off. Because it runs alongside the eMule networks rather than replacing them, taking part costs you nothing on KAD or eD2K.

How a node joins

There is no bootstrap server to ask and no address list in the installer. A cold node gets in through whichever of these arrives first:

1. The KAD rendezvous key
   Ember nodes advertise themselves under one fixed KAD key, as an ordinary source record carrying their Noise public key. A node with a near-empty routing table simply runs a source lookup there. Nodes re-advertise every 5 hours, while they are reachable enough to be a useful first contact. Sharing a library is not required — a node that can answer a DHT ping is worth listing whether or not it publishes anything — but a firewalled node that cannot be reached directly is left out.
2. The KAD bridge
   Ember peers noticed in ordinary KAD traffic get pinged on the Ember DHT; their signed reply folds them into the routing table. Rate-capped per maintenance cycle and quiet once the table is healthy.
3. eD2K transfers
   A peer that advertises Ember capability during a normal eD2K transfer is cached with its UDP port and bridged in. This is the way in for a client running with no KAD at all.
4. Gossip and the saved contact file
   Once a node has been online before, peers learned from other peers plus a persisted contact file (up to 200 entries) get it back in without help.

The first three paths all assume either a live KAD connection or an eD2K transfer with an Ember-capable peer, and the fourth only helps a node that has been online before. That is deliberate: Ember rides eMule’s bootstrap rather than standing up infrastructure of its own. The practical consequence is worth knowing — a first run with KAD off and no servers has no way in.

Search and publishing

The files you share are published to the Ember DHT as keyword records (so people can find them by name) and source records (so people can fetch them). Publishing happens automatically once the node has peers, and republishes on a cycle to stay alive.

• Searching — The Search page has an Ember only method, and All networks queries Ember alongside KAD and servers, merging everything into one de-duplicated result list. If KAD and eD2K are both offline, All networks quietly falls back to Ember alone.
• What a result carries — A keyword record holds the file’s media details (duration, bitrate, codec, artist, album, title) alongside its name and size, so an Ember hit fills the same columns an eD2K server hit fills. Your library is probed once and the answer is persisted — including “nothing to find”, which is the answer for most of a library and has to be as durable as a positive one.
• Complete sources — Only complete public shares are keyword-published, so the count of distinct publishers who signed a record is a floor on the complete sources. That is a firmer number than a server or KAD swarm estimate, which is one peer’s claim about a swarm it cannot see — and the Sources column says which of the two it is showing.
• Filters that cost the network nothing — Size, type and extension travel with the query as constraints the responder applies before it packs an answer, rather than as published keys. An indexed .mp3 would be the hottest key on the network, with every mp3 anyone shares competing for one key’s slots on the twenty nodes nearest it.
• Source lookup — Downloads ask the Ember DHT for sources in addition to KAD and servers, so a file can gain Ember sources even if you found it elsewhere. Find Sources on a transfer asks every network that is connected.
• Publish badge — The Library marks a shared file with an Ember badge once it has a source record placed on the network, which is the point at which other Ember users can actually fetch it.
• Publishing while firewalled — A node that cannot be reached directly publishes through a buddy relay instead, so sharing still works behind a restrictive router.
• BLAKE3 integrity — Ember records carry a BLAKE3 digest, and a download verifies against it whenever one is known (from a search hit, a DHT source record, or your own library). A match shows an Ember badge on the finished row; a mismatch fails the download instead of retrying parts that already matched. Links opened without a digest still download normally and are hashed for future sharing.

Encryption and identity

Ember DHT traffic shares the KAD UDP port (4672 by default) and is told apart by a two-byte marker, so forwarding that port covers both networks, and Ember’s QUIC transfers, which share the same socket by default. Everything past the marker is encrypted.

The full wire format — every frame and its encoding, the signing and session rules, the version negotiation, and the storage and admission limits — is written up in the EmberDHT Protocol Specification, also available as a PDF. It is written against wire version 4, as implemented in this release, and marks each change since v3 as additive or breaking, which is the distinction another implementation needs.

The Ember Network page

The page leads with the questions a user actually has — is it on, am I connected, can people reach me, are my shared files findable — and keeps the protocol detail behind a disclosure.

• Status — Connecting, Connected, or No peers found. There is nothing to switch: the overlay reports what it is doing, it does not ask you to start it.
• Peers and Published files — How many nodes you are in touch with, and how many of your shared files are findable.
• Health checklist — Whether people can reach you directly or through a relay (or are still waiting for one), and whether your shares are published. Whether you are on the network is the status line above it.
• Technical details — Collapsed by default: your node ID and public keys, the protocol counters (search hits and misses, store acks and failures, truncated and withheld answers, average replication, buddy publishes and forwards, malformed frames, version mismatches, observed address votes, EPX exchange stats, storage rejections), plus live tables of contacts, in-flight searches, and the keys this node is serving to others.

Current limits

The overlay is always on and in daily use, but these are the things it does not do yet:

• Bootstrap depends on eMule — A first run with KAD off and no servers cannot join, as described above.
• A peer that needs to update cannot be told so — Incompatible peers refuse each other cleanly at the version byte. Your side is not in the dark about it: refusals are counted, split into peer-older and peer-newer, and the Ember page raises a banner while older peers are being turned away. The other half cannot be fixed from here, because the peer that needs to update is by definition the one that cannot decode anything we send. Builds now advertise which versions they can decode on PING and PONG, so a future change to an existing frame can be negotiated rather than partitioning the overlay on the day it ships — but that only helps between peers that both carry it.
• Multi-keyword recall is approximate — See the note above.
• A busy keyword is answered a page at a time — One packet still only carries a few records, but a searcher can ask the same peer for the next page, so recall under a common word is bounded by how many peers the search walks and how deep it pages rather than by one datagram. A peer is held to a quarter of a search’s budget while the walk still has somewhere to go, and may serve the rest of it once there is nothing left to ask — so a single node holding an uncommon word can hand over its whole index instead of the first slice of it. Publishing has its own ceiling: a key holds 1000 records and any one publisher at most 150 of them, matching KAD’s numbers, so if you share far more than 150 files under one common word not all of them are findable under it. The Ember page counts how often an answer was truncated or records were withheld.
• Gossip is unverified until it answers — A peer another node told us about is a lead, not a fact, until it replies directly. The Ember page, status bar, and Search readiness wait for a verified answer before calling the overlay connected, so a table full of gossip does not look like a successful join. Admission caps bound the damage, and a peer whose introductions almost never answer has its leads probed less often. It is still sampled, so it can recover, and no contact is refused on that basis alone.
• Library content still moves over eD2K — Ember finds the source; the bytes travel the eMule wire. The exceptions are a file sent to a friend in chat or to a member of a room, which goes directly between the two of you (accept-first, up to 2 GB). Putting ordinary downloads on the same footing is the largest remaining piece.
• Some paths are not yet exercised end to end — Notably publishing while firewalled through a buddy relay, and a cold join from an empty contact file with no KAD.

EPX — Ember Peer Exchange

EPX is an Ember-exclusive extension to the eMule protocol that accelerates source discovery between Ember peers. It makes downloads faster whenever multiple Ember clients are present on the network.

EPX and the Ember Network are separate things that are easy to confuse. EPX is an extra opcode on the eMule wire, exchanged with Ember peers you are already transferring with. The Ember Network is a whole overlay of its own, with its own DHT and its own encrypted transport. Both work independently: EPX helps with any Ember peer you are transferring with, whether or not that peer is in your Ember DHT routing table. (The overlay itself is always on in this build; there is no switch to turn it off.)

How it works

When two Ember clients connect (during a download or upload), they exchange compact lists of the files they are currently downloading along with the sources they know about for each file. If the receiving peer is downloading one of those files, it immediately gains new sources it may not have found through KAD or ED2K peer exchange alone.

Wire Protocol

EPX uses opcode 0xF0 on the eMule extended protocol (OP_EMULEPROT). The current version is v4. The payload format:

version       (1 byte, currently 0x04)
file_count    (u16 LE)
  for each file:
    ed2k_hash   (16 bytes)
    file_size   (u64 LE)
    file_flags  (u8, bit 0 = has AICH root hash)
    aich_root   (20 bytes, only present if bit 0 of file_flags is set)
    source_count (u16 LE)
      for each source:
        ipv4      (4 bytes, network order)
        tcp_port  (u16 LE)
        udp_port  (u16 LE)
        flags     (u8, bit 0 = firewalled, bit 1 = obfuscation, bit 2 = relay-capable)
peer_count    (u16 LE)
  for each peer:
    ipv4      (4 bytes, network order)
    tcp_port  (u16 LE)
[optional ERAT trailer]

v4 is layout-identical to v3 for the main body and adds the relay-capable flag bit plus an optional ERAT relay-attestation trailer. v3 parsers ignore unknown flag bits. v3 additions over v2: per-file AICH root hashes for corruption recovery, UDP port and capability flags per source, and a peer discovery section for Ember mesh building. v2 and v3 payloads are still accepted.

ERAT relay attestations

After the peer list, a v4 packet may append a trailer beginning with magic ERAT: version byte, attestation count (max 16), then fixed-size Ed25519-signed entries binding a relay IP/port to an expiry and capability bits. Only cryptographically valid, non-expired attestations (max TTL 30 minutes) become connection-broker relay candidates. The per-source relay-capable flag alone never admits a relay.

Peer-relay QUIC RELAY_REQUEST messages are version 2 or 3 and require proof of possession: the requester includes their Ed25519 public key and Ember hash, a fresh nonce, and a signature over the session id, the relay's ERAT attestation hash, target address, and file hash. Legacy hash-only (bearer) requests are rejected. Relays also reject replayed nonces within a short TTL window.

The target port in the request is the port the relay dials over QUIC. For Ember DHT sources, that is the QUIC port the source advertises in its record. Version 3 adds the target's Ember node id ahead of the signature, which is made under a separate domain, and the relay then refuses to bridge to any endpoint whose QUIC certificate does not prove that id. A relay advertises support with ERAT capability bit 0x02. Requesters send version 3 only to relays with that bit, because older relays accept no request length other than version 2's. A relay also holds at most two sessions per requester, and it closes a bridge after two minutes in which neither direction moves a byte.

The relay answers only once it has reached the target. RELAY_ACCEPT means the bridge is up; RELAY_REJECT carries a reason byte for capacity, a target it will not dial, a requester that is not its friend or an attestation it does not know, a bad signature or replayed nonce, or a target it could not reach, and none of these counts against the relay. A requester asks one relay for no more sessions at once than it would hold, sends the next to another relay, and keeps the newest copy of a relay’s attestation when an older one comes round again. A relay with no room left can only close the connection or refuse the handshake, and the requester then skips it for a minute; a refused handshake still counts against it, because anyone at that address could send one. Within a bridge, a side that finishes its stream has that passed on at once, and what the relay still holds for either side when the bridge ends is given up to ten seconds to arrive before the connections close.

Safety Limits

These caps prevent abuse from poisoned or malicious payloads. Private/reserved IPs and zero-port entries are silently dropped.

The 64 KB ceiling is the TCP path, which streams. UDP EPX has to fit inside a single Noise datagram, so it is packed to a much smaller budget — the same files and sources, just fewer of them per reply.

Backward Compatibility

Non-Ember eMule clients silently ignore the 0xF0 opcode — it causes no errors, disconnects, or side effects. EPX is only sent to peers confirmed as Ember through the private OP_EMBER_HELLO handshake, so a stock client never triggers it.

Friends — Ember-Exclusive Social

Ember includes a built-in friend system that works exclusively between Ember users. It is powered by a separate cryptographic identity called the Ember Hash (also known as your Friend ID), which is distinct from the standard ed2k user_hash used for protocol operations and credits.

How it works

Each Ember client generates a unique 16-byte Ember Hash on first launch. Share a Friend Code (shown on the Friends page) with someone so they can find you on the network. A Friend Code (ember3:) carries your identity plus a random secret, so only someone you gave it to can look up where you are — a public key seen in a room roster is not enough. Friends > Reset code makes a new secret; Ember still accepts older ember2: codes and bare Friend IDs.

Friend discovery is powered by a lightweight rendezvous server. When you connect, Ember registers presence using hashed capabilities (never your raw Friend ID in the clear). When you search for a friend, Ember queries the server and gets back an IP and port for a direct connection. Adding or accepting a friend forces a presence refresh so discovery does not wait on the normal heartbeat interval.

Once a friend is found, Ember opens a direct TCP connection and establishes a Noise IK secure stream with Ed25519 proof-of-possession. After both sides accept the friend request, chat, file browsing, file offers, friends-only shares, and priority uploads unlock on that secured session. When both friends are behind difficult NAT, Ember can still move friend file traffic over the secure session (and optional peer relay) without waiting for HighID.

Features

• Friend Codes — Share a Friend Code from the Friends page instead of only a raw Friend ID. Codes support privacy-preserving pairwise presence so mutual chat and browse can unlock once both sides have added each other. Codes made by 1.7.0 and later start with ember3:, which 1.6.x cannot read.
• Mutual Friend Requests — The recipient sees an incoming request on the Friends page and can accept or reject it. Chat, file browsing, offers, and priority upload features only activate once both sides have accepted and a secure friend session is established.
• Real-Time Online Status — Ember detects when a friend comes online and shows a live online/offline indicator on their card. The Friends page also surfaces when you are not currently discoverable on the rendezvous network.
• End-to-End Encrypted Chat — Send and receive messages with mutual friends through a slide-out sidebar. After session setup, messages are encrypted end-to-end, marked by a lock icon in the chat window. Outbound messages queue locally and retry when the friend reconnects. The chat can also pop out into its own window. See E2E Encryption.
• Send Files in Chat — Attach a file to a conversation and it goes directly to that friend, up to 2 GB, over QUIC or, when the sender’s UDP port is not reachable, an encrypted stream on their TCP upload port. Each piece is checked against the offered hash as it arrives. Received files are saved to a Chat Files folder, small ones can download automatically, and programs, scripts and disguised files carry a warning. Both of you need 1.7.0, and files are not sent through relays.
• Remote File Browsing — Browse a mutual friend’s shared file library while they are online and start downloads directly from the browse results.
• Friends-Only Shares — Mark Library files as friends-only so they stay out of public search and only mutual friends can request them.
• Friend File Offers — Push a specific shared file to a mutual friend from the Friends page. Offers appear as actionable notifications the recipient can accept or decline.
• Friend Transfers Without HighID — Mutual-friend downloads can use the Noise-secured friend session (and optional Ember peer relay) when ordinary HighID or callback paths are unavailable—useful when both sides are behind difficult NAT.
• Priority Upload Slots — Anyone you have added as a friend gets priority in your upload queue on an authenticated Ember friend session, giving them faster access to your shared files. This one is deliberately one-sided: it costs you only queue position, so it does not wait on them adding you back. Friends-only shares and remote browse do.
• Friend Block List — Block a Friend ID so future requests, chat, browse, and offers from that identity are rejected. Existing mutual friendships with that identity are removed when you block.
• Optional Peer Relaying — Relay for other peers (Settings > Network) lets peers who cannot reach each other directly route through you, which is what makes LowID↔LowID transfers work behind strict NATs when attestations allow. It spends your upload bandwidth on people you are not trading with, so you can turn it off.
• Discoverable Banner — The Friends page shows a confirmation banner when your identity is registered and discoverable, and warns when presence registration failed so friends may not find you.

E2E Encryption

Friend chat is designed so the rendezvous server and any on-path observer never see message plaintext after a secure session is up.

• Noise IK sessions — Friend connections negotiate a Noise_IK secure stream authenticated with Ed25519 proof-of-possession before chat, browse, offer, and friends-only privileges unlock.
• End-to-end chat crypto — Message bodies are sealed with XChaCha20-Poly1305 under a key derived from a static X25519 exchange between the two friends’ identity keys. After session setup, plaintext chat fallbacks are rejected. Outbound messages that cannot be delivered stay queued and are retried on reconnect.
• Encrypted local history — Conversation history is encrypted at rest in the local database, under a key kept beside it. If that key cannot be recovered, history stays sealed and says so rather than failing quietly.
• Clear UI signals — A lock icon in the chat window and on online mutual friends’ cards marks encrypted chat (its tooltip says what is and is not protected), and reconnect-oriented errors when encryption or the friend session fails.

Privacy

The rendezvous server stores presence as hashed capabilities derived from your Friend identity (never the raw Friend ID in the clear), paired with IP and port. Registration is pubkey-bound and signature-checked so entries cannot be spoofed with a stolen hash alone. Entries expire automatically after 5 minutes without a heartbeat. Between Ember peers, the Ember Hash is exchanged via the private OP_EMBER_HELLO / OP_EMBER_HELLOANSWER handshake (with Ed25519 proof-of-possession on TCP) — not via the legacy EmuleInfo path used for ordinary eMule metadata.

Channels Beta

Channels are group chat rooms carried over the Ember Network itself. No server hosts a room and no company runs one: messages travel encrypted between the members over the same overlay that carries search and source lookup. Room and user names are registered with the rendezvous server; messages never pass through it. Members never publish their IP address to the room.

Friends are for people you know one-to-one. Channels are for a group — a room you can hand an invite to, hand off to someone else, or leave running after you have gone.

Getting started

1. Pick a Channel username
   Two to twelve letters or numbers, and it has to be free — the name is claimed in Ember’s rendezvous directory so two people in a room are never the same “Ada”. This is separate from your friend nickname, and you need one before you can create or join anything.
2. Create a room, or join one
   A room name is up to 32 characters and is claimed first come first served; the owner can rename the room later. To join someone else’s, paste the ember-channel: invite they sent you.
3. Or find one with Discover
   Discover lists public rooms that other people have published. Private rooms never appear there.

Public and private rooms

The choice you make when you create a room is the one that matters most, and it cannot be changed afterwards.

• Public — listed in Discover so anyone can find and join it. Anyone who finds it can also read it: the key that unlocks the conversation is derived from the address in its public listing. A public room is a public conversation.
• Private — never listed. Joining needs an invite link, which carries the key. If the conversation should stay with the people you invite, this is the one to use.

A private room’s owner can rotate its key, which cuts off anyone holding an older invite — the remedy when a link has been shared further than you meant.

Running a room

Whoever creates a room owns it. Owner tools open in a room settings window from the gear in the room header.

• Rename — give the room a new name, up to 32 characters.
• Topic and welcome — a line at the top of the room and a greeting new members see.
• Language — mark the language the room is held in. It shows as a small flag beside the name in the room list, the header and Discover.
• Pins — pin up to 3 messages to the top of the room, from a message’s own menu.
• Announcements only — only you and your moderators can post; members can still read and react. Each member’s own app enforces it, so a member on an older build is not held to it.
• Moderators — up to 6 members who can ban and unban on your behalf. They cannot ban you, and they cannot delete the room.
• Bans — up to 12 at a time.
• Owner-only invites — stops a member re-sharing the room without thinking. Every member holds the key either way, so treat this as a guard against carelessness rather than against someone determined.
• Slow mode — sets how long members wait between messages, from 5 seconds to 5 minutes. Off unless you turn it on. You and your moderators are exempt, and everyone in the room can see it is on.
• Rotate the key — private rooms only, for when an invite has leaked.
• Hand the room over — transfer ownership to a member, or nominate a successor who can claim the room if you go quiet for a window you choose. Better than sharing your key.
• Delete — permanent. The room name is retired and cannot be claimed again.

One device can own up to 10 rooms at once. Deleting a room gives the slot back. Joining rooms is not limited.

Every member, owner or not, can mute a room so it stops raising notifications, and ignore a member so their messages are hidden. Both are private to your device and are listed under Settings > Channels, where you can undo them.

Messages

• Edit your own message for 15 minutes after sending it. Every receiver checks the author’s signature and both clocks itself, so “only the author may edit” is not something the sending client is trusted about. Members who were away are handed the corrected line rather than the original followed by a revision.
• Reply to a message and your line quotes the one it answers. A member on 1.6.x sees the reply as an ordinary line.
• React with one of 20 reactions. One reaction per person per message, and changing yours replaces it. The original thumb up, thumb down and heart work with 1.6.1 and newer; the others need 1.7.0.
• Format with **bold**, *italic*, ~~strike~~ and `code`. Formatting is only how the line is shown; an older Ember shows the marks as typed.
• See who is typing, on 1.7.0.
• Remove a message from this device. Local only — the protocol has no way to unsend, so every other member keeps their copy. What it does guarantee is that the line stays gone here, including when another member replays it later.
• Mention a member by typing @, which completes handles from the room’s member list.

Edits and reactions need both sides on 1.6.1 or newer. An older client does not recognise them and drops them rather than passing them on, so in a mixed room they reach only the members who have updated.

Sending files

You can send a file to one member of a room at a time, up to 2 GB, and only after they accept the offer. An offer that goes unanswered lapses after 5 minutes, and up to 4 transfers can run at once. Files go directly between the two of you, not to the whole room, and the payload is encrypted to that member rather than to the room. Transfers count against your upload speed limit like any other upload, and appear in a drawer under the member list with their speed and time left.

Between two members on 1.7.0 the file moves over a direct QUIC stream, or an encrypted stream on the sender’s TCP upload port when their UDP port cannot be reached, and each piece is checked against the offer as it lands. If neither can be opened — a member on 1.6.x, or two firewalled members who can only meet through a relay — the transfer falls back to the older block protocol, which is much slower, keeps what was already verified, and is limited to 100 MB for a 1.6.x member. Received files are saved to a Channel Files folder, which is not shared, and programs, scripts and disguised files carry a warning.

What to expect

• Moderation is local. A ban stops honest clients from showing that member and stops them being served. It is not a network-level eviction, and someone running a modified client can ignore it.
• Public listings can be spammed. Discover shows what people published, and nobody vets it.
• A room holds up to 256 members and a message up to 4096 bytes.
• History is what your device kept. Rooms are not archived anywhere central. When you join, members near you share recent messages; older conversation you were not present for is gone.
• Search inside a room looks only through the history your device has.

Network Compatibility

Ember is a first-class citizen of the eMule network. It implements the full protocol suite required to participate alongside every other eMule-family client.

Port Forwarding

Ember uses two port numbers for peer communication. Both are configurable in Settings > Network.

For best performance (High ID), forward 4662 TCP and 4672 UDP on your router, and 4662 UDP as well if you forward by hand (UPnP maps it for you), enable UPnP for automatic mapping, or use STUN port keep-alive when you are behind CGNAT or full-cone NAT without UPnP.

High ID vs Low ID

An ID is a value calculated from the client's IP address and assigned by the ED2K server when Ember connects for peer exchange. It indicates whether proper bidirectional communication is possible.

High ID

A High ID means your connection port is open and freely accessible from the internet. Your client is fully reachable by others. This is the optimal state.

Low ID

A Low ID means your connection port is blocked or cannot be reached, typically caused by firewalls, routers, or NAT. Any ID value less than 16,777,216 is considered a Low ID.

Disadvantages of a Low ID

• Peer Routing — Since your IP is not directly reachable, all requests must be routed through the server, increasing overhead.
• Reduced Sources — On the ordinary eD2K path, two Low ID clients cannot connect to each other, so you see fewer sources. Ember can route around some of those cases through a peer relay, and mutual friends can use a Noise session without either side holding a High ID, but neither is a substitute for opening the port.
• Lost Messages — On busy servers, messages can get lost, causing missed queue progression and slower downloads.

Troubleshooting Low ID

If you're stuck with a Low ID despite correct settings:

• Verify that ports 4662 (TCP) and 4672 (UDP) are forwarded on your router.
• Check that your OS firewall allows Ember through on both protocols.
• Restart Ember to reconnect to the ED2K server.
• Enable UPnP in Settings > Network for automatic port mapping.
• Leave STUN port keep-alive enabled (Settings > Network) if you are behind CGNAT or full-cone NAT without UPnP — Ember will try to hold and advertise remapped public ports.
• If behind symmetric NAT or a VPN that remaps ports unstably, STUN keep-alive suspends automatically; High ID may still require a VPN with a fixed forwarded port or another tunneling solution.

Tech Stack

For Developers

Protocol documentation

Ember’s eMule-side behaviour follows the published eD2K and KAD protocols. Its own overlay is specified in the EmberDHT Protocol Specification (PDF) — wire version 4, as implemented in this release — which is enough to write an independent implementation that joins the same network.

Prerequisites

• Rust (1.94+)
• Node.js (22.12+ or 24+)
• Windows: Visual Studio Build Tools with C++ workload

Development

# Install dependencies
npm install

# Run in development mode
npm run tauri dev

# Build for production (updater artifacts need the release signing key)
npm run tauri build -- --config '{"bundle":{"createUpdaterArtifacts":false}}'

Without that override, or TAURI_SIGNING_PRIVATE_KEY set, the build stops at the updater-signing step. On Windows the production build produces NSIS and MSI installers in src-tauri/target/release/bundle/. A Linux build from the same tree produces the same .deb and AppImage the official release publishes, unsigned.

Project Structure

Contributing

Ember is licensed under the GPLv3 and welcomes contributions. Visit the GitHub repository to open issues, submit pull requests, or review the codebase.

FAQ

Answers to the questions people ask most. Click a question to expand it.

Support

Report an Issue

To report a bug or suggest an improvement, please use the GitHub Issues page.

What to include in a good report

• The exact Ember version (shown in the About dialog).
• Your operating system and version (Windows build or Linux distribution), and how you installed Ember (installer, MSI, .deb or AppImage).
• Clear step-by-step instructions that reproduce the problem.
• What you expected to happen and what actually happened instead.
• Relevant screenshots or log excerpts if applicable.

Community & Source Code

Visit the Ember GitHub repository to browse source code, review open issues, or contribute. Ember is GPLv3-licensed and contributions are welcome.