Ketch

A full-featured Kotlin Multiplatform download manager — run locally, remotely, or embedded in your app. Supports Android, iOS, Desktop, and Web.

• Embed it — Add downloads to your Android, iOS, or Desktop app with a simple API
• Run it as a daemon — Self-hosted download server with REST API and real-time SSE events
• Control it remotely — Manage a daemon from any client (desktop or mobile app, or the web UI)
• Extend it — Pluggable architecture for custom protocols (FTP and BitTorrent ship as modules; HLS and more on the roadmap)

Warning

🚧 Work in Progress — This project is under active development. APIs may change. Contributions and feedback are welcome!

Features

• Multi-platform ✅ -- Works on Android, iOS, Desktop, and Web
• Segmented downloads ✅ -- Accelerate downloads by splitting files into multiple parallel connections
• Multi-network downloads ✅ -- Distribute HTTP segments across multiple network interfaces on JVM/Desktop and Android, configurable locally or remotely through KetchApi (setup and limitations)
• Pause / Resume ✅ -- Pause and pick up where you left off, even after restarting your app
• Queue management ✅ -- Manage multiple downloads with priorities and concurrency limits
• Speed limiting ✅ -- Control bandwidth usage per task or globally
• Scheduling ✅ -- Schedule downloads for a specific time, after a delay, or based on conditions
• Automatic retry ✅ -- Automatically retry failed downloads with smart backoff
• Daemon server ✅ -- Run as a background service with REST API and real-time events
• Remote control ✅ -- Manage a remote server from any client (mobile, desktop, or web)
• Pluggable architecture ✅ -- Swap out HTTP engines, storage backends, and download sources
• FTP/FTPS ✅ -- Download from FTP servers with segmented parallel transfers and resume
• BitTorrent & Magnet -- Pure Kotlin v1, v2 and hybrid downloads on JVM, Android, and iOS
• Metalink 🔜 -- Multi-source downloads with mirrors, checksums, and chunk verification
• WebDAV 🔜 -- Download from WebDAV servers with resume support
• HLS streaming 🔜 -- Download and merge HTTP Live Streaming videos
• Media extraction 🔜 -- Extract and download media from websites (like yt-dlp)
• Resource sniffer 🔜 -- Detect downloadable resources from web pages
• Browser extension ✅ -- Send downloads, links and magnet links from Chrome, Edge, Firefox and other browsers to Ketch on this computer or a remote server
• AI-driven discovery 🚧 -- Find download links from natural language queries using an LLM agent you configure in the app (OpenAI, Anthropic, Gemini, Ollama, or any OpenAI-compatible endpoint), or with ketch ai-discover
• MCP server 🚧 -- Expose Ketch capabilities as tools for AI agents via Model Context Protocol with ketch mcp

Getting Started

Embed in Your App

Add the SDK to your Kotlin Multiplatform project:

// build.gradle.kts
dependencies {
  implementation("com.linroid.ketch:core:<latest-version>")
  implementation("com.linroid.ketch:ktor:<latest-version>")
}

Start downloading:

val ketch = Ketch(
  httpEngine = KtorHttpEngine(),
  config = DownloadConfig(
    maxConnectionsPerDownload = 4,
    maxConcurrentDownloads = 3,
  )
)

val task = ketch.download(
  DownloadRequest(
    url = "https://example.com/large-file.zip",
    destination = Destination("/path/to/downloads/"),
  )
)

// Observe progress
task.state.collect { state ->
  when (state) {
    is DownloadState.Downloading -> {
      val p = state.progress
      println("${(p.percent * 100).toInt()}%  ${p.bytesPerSecond / 1024} KB/s")
    }
    is DownloadState.Completed -> println("Done: ${state.outputPath}")
    is DownloadState.Failed -> println("Error: ${state.error}")
    else -> {}
  }
}

To distribute HTTP segments across Wi-Fi, Ethernet, or Android cellular networks, see multiple network interfaces.

See Installation for version catalog setup, optional modules (SQLite persistence, Kermit logging, remote client), and the full API reference.

Download the App

Download the latest apps from GitHub Releases:

Platform	Format
Android	.apk
macOS (x64, arm64)	.dmg
Linux (x64, arm64)	.deb
Windows (x64, arm64)	.msi
iOS	Build from source via Xcode
Browser extension (Chromium, Firefox)	.zip (how to install)

CLI / Server

Install the native CLI to run Ketch as a daemon on your server:

curl -fsSL https://raw.githubusercontent.com/linroid/Ketch/main/install.sh | bash

Then start the daemon:

# Start the server with REST API + web UI on port 8642
ketch server

# Download a file directly
ketch https://example.com/file.zip

# Use a TOML config file
ketch server --config /path/to/config.toml

Supported platforms: macOS (x64, arm64), Linux (x64, arm64), Windows (x64). See the CLI documentation for all commands, flags, and config file reference.

Browser Extension

The browser extension hands downloads from Chrome, Edge, Brave, Opera, Firefox and other browsers to Ketch. It captures downloads you start, adds Download with Ketch to the context menu, and takes over magnet links. It can send to the Ketch app on this computer (turn on Settings → Remote access → Server, or run ketch server) and to any number of remote servers.

How It Works

1. Resolve -- Query the download source (HEAD request for HTTP) to get size, range support, identity headers
2. Plan -- If ranges are supported, split the file into N segments; otherwise use a single connection
3. Queue -- If max concurrent downloads reached, queue with priority ordering
4. Download -- Each segment downloads its byte range concurrently and writes to the correct file offset
5. Throttle -- Token-bucket speed limiter controls bandwidth per task and globally
6. Persist -- Segment progress is saved to TaskStore so pause/resume works across restarts
7. Resume -- On resume, validates server identity (ETag/Last-Modified) and file integrity, then continues (servers without range support restart from the beginning)

Documentation

• Architecture -- Modules, dependency graph, download pipeline, and multi-backend design
• API Reference -- Installation, module interfaces, configuration, error handling, and logging
• Logging -- Logging system and configuration
• AI discovery -- Providers, tokens, web search, and environment variables
• BitTorrent -- Torrent and magnet support, configuration, and limitations
• Multiple networks -- Distributing downloads across network interfaces
• CLI -- Command-line interface for downloads, the daemon, MCP, and AI discovery
• Browser extension -- Setup, capture rules, permissions, and development

Contributing

Contributions are welcome! Please open an issue to discuss your idea before submitting a PR. See the code style rules and testing rules for development guidelines.

Coding agents should start with AGENTS.md, the shared instructions for all agents and editors. If your tool does not load it automatically, ask it to read AGENTS.md and its linked rules before making changes. Keep shared instructions in these files; tool-specific entry points should only reference them.

License

Apache-2.0

---

Built with Claude Code by Anthropic.