# kachok

> A BitTorrent client written in Kotlin: a Compose Desktop window, a headless command-line client and a Model Context Protocol server, all three on one common engine. On the desktop it runs on JDK 25, one virtual thread per peer.

Page: https://kotlin.website/kachok

## Why it exists

[kachok](https://github.com/youndie/kachok) is a BitTorrent client written to find out what a modern
JDK makes of a protocol that is mostly waiting on sockets. The engine is common Kotlin — bencode, the
peer wire protocol, piece selection, choking, storage, the DHT — and the I/O behind it is whatever the
platform does best. On the desktop that is JDK 25: one virtual thread per peer on a blocking socket,
and a pool of 16 KiB direct buffers that travel from the socket to the disk without a copy.

It is also the largest application built on two of the Compose libraries here. The window sits in an
[appframe](https://kotlin.website/appframe) frame, and its interface comes in two kits chosen on the settings screen —
Material, the default, and [oldge-ui](https://kotlin.website/oldge-ui) in any of its skins. Many of oldge-ui's issues were
filed from kachok, by a window that needed the component.

## What it does

- **Downloads and seeds** from a `.torrent` or a `magnet:` link, and resumes both across a restart —
  the resume record is an optimisation and the disk is the source of truth.
- **Finds peers four ways** — trackers over HTTP and UDP, the DHT, peer exchange and local discovery —
  and asks a router to forward its port over UPnP or NAT-PMP.
- **Speaks the extensions a modern swarm expects**: the fast extension, the extension protocol,
  metadata from peers so a magnet becomes a torrent, IPv6 where the tracker offers it, and encrypted
  connections, dialled first and fallen back from.
- **Lets you choose what arrives and when** — files skipped or raised, sequential download, limits
  for the whole client, a cap on downloads at once, pause and re-check.
- **Stays out of the way** — a tray icon, `.torrent` file associations, a clipboard offer when a
  magnet is on it, installers for macOS, Windows and Linux.

## Three ways in

**The window** — `./gradlew :ui:run`, or an installer from
`./gradlew :ui:packageReleaseDistributionForCurrentOS` (`.dmg`, `.msi`, `.deb`).

**The command line** — a headless client that prints one progress line a second, and a `jlink`
image with an ahead-of-time cache that runs on a machine with no JDK:

```bash
./gradlew :cli:run --args="download ubuntu-26.04-desktop-amd64.iso.torrent --dir ~/Downloads --seed"
```

**An agent** — `kachok mcp` is a Model Context Protocol server on stdin and stdout. It is a third
adapter on the same engine rather than a second client: every tool is a call the window makes too —
add, list, wait for completion, pause, prioritise a file, set limits — and every refusal is a
sentence naming the torrent, the path and what was wrong.

```json
{
  "mcpServers": {
    "kachok": { "command": "kachok", "args": ["mcp", "--dir", "/home/you/Downloads"] }
  }
}
```

## How fast

Same public torrent, same machine, same link, one client at a time, three minutes each, upload capped
at 800 KiB/s on both:

| | kachok | qBittorrent 5.2.1, twice |
|---|---|---|
| downloaded | 3.31 GiB | 3.51 and 3.04 GiB |
| rate | 19.7 MiB/s | 20.0 and 17.3 MiB/s |

The window runs in a 64 MiB heap; the largest surfaces it holds are Skia's and are not on it.

## What it does not do

- **µTP.** Every connection is TCP, and 65 % of dials on a public swarm time out because the peer is
  behind a NAT only µTP would reach. Deferred with its reasoning, not forgotten.
- **Version 2 torrents** — still an open question rather than a plan.
- **Android, iOS and the browser.** The engine is written to be lifted onto them, but only the
  desktop is built.
- **Anything over a network it did not open.** The WebSocket for clients outside the process is bound
  to loopback and has no authentication, by decision.
