Local network toolkit.
Koi is a cross-platform local network toolkit. It bundles service discovery (mDNS/DNS-SD), a local DNS resolver for friendly names, and a private certificate mesh for LAN TLS. It ships as a single binary with HTTP, IPC, and CLI interfaces, so any language or container can use it.
Think of it as the missing LAN toolbox: discover services, name them, and secure them without installing a stack of OS-specific daemons.
# Discover what's on the network
koi mdns discover
# Resolve a friendly local name
koi dns lookup grafana
# Add a static DNS entry
koi dns add grafana 10.0.0.42
# Check unified status
koi status
# Open the web dashboard
koi launchOr over HTTP - from any language, any container, any script:
curl http://localhost:5641/v1/mdns/discover?type=_http._tcp
curl -X POST http://localhost:5641/v1/mdns/announce \
-d '{"name": "My App", "type": "_http._tcp", "port": 8080, "ip": "192.168.1.42"}'Install Koi as a system service (recommended):
# Windows (run as Administrator)
koi install# Linux / macOS
sudo koi installKoi is now running on port 5641, ready for HTTP, IPC, and CLI clients.
For temporary or interactive use, run in the foreground instead:
koi --daemonmDNS is the invisible backbone of local networking. Printers, smart speakers, AirPlay, Chromecast, IoT devices - everything uses it. But using mDNS programmatically is surprisingly painful:
- Windows has native mDNS since Windows 10, but the Win32 APIs are poorly documented, 64-bit only, and don't expose full DNS-SD. The alternative - Apple's Bonjour - has redistribution-prohibiting licensing and a 13-year-old installer.
- Linux has Avahi, which is excellent but Linux-only and deeply coupled to D-Bus and systemd.
- Containers can't do mDNS at all. Docker's bridge network doesn't forward multicast traffic. Every workaround (
--network=host, macvlan, mDNS reflectors) sacrifices isolation or adds fragility. - Cross-platform libraries exist, but they're libraries - you need to write code in a specific language to use them.
Koi fills the gap: a single daemon that speaks mDNS on the network side and JSON over HTTP/IPC/stdio on the application side. Any language with an HTTP client or the ability to spawn a process can discover, name, and secure services on the local network.
When Koi runs on the host, every container gains LAN capabilities through plain HTTP - no --network=host, no macvlan, no mDNS reflectors.
# From inside any Docker container:
curl http://host.docker.internal:5641/v1/mdns/discover?type=_http._tcp
curl http://host.docker.internal:5641/v1/dns/lookup?name=grafanaSee CONTAINERS.md for Docker Compose examples, startup patterns, and Kubernetes DaemonSet configuration.
| Capability | What it does | CLI | Guide |
|---|---|---|---|
| mDNS | Service discovery (DNS-SD) | koi mdns ... |
mDNS guide |
| DNS | Local resolver for friendly names | koi dns ... |
DNS guide |
| Certmesh | Private CA + enrollment for LAN TLS | koi certmesh ... |
Certmesh guide |
| Health | Machine/service health monitoring | koi health ... |
Health guide |
| Proxy | TLS-terminating local reverse proxy | koi proxy ... |
Proxy guide |
| UDP | Datagram bridging for containers | HTTP API | UDP guide |
The daemon also serves a web dashboard at http://localhost:5641/ with a system overview and an mDNS network browser at /mdns-browser. Interactive API docs are at /docs (OpenAPI/Scalar).
| Platform | mDNS engine | Service integration |
|---|---|---|
| Windows | Pure Rust (no Bonjour needed) | Windows Service (SCM) |
| Linux | Pure Rust (no Avahi needed) | systemd unit |
| macOS | Pure Rust (no Bonjour needed) | launchd plist |
Zero OS dependencies. No Bonjour, no Avahi, no system mDNS service required.
Download the latest release from GitHub Releases. Extract and place koi (or koi.exe) on your PATH.
Requires Rust 1.75 or later.
git clone https://github.com/sylin-org/koi.git
cd koi
cargo build --releaseOr install from crates.io:
cargo install koi-netUsing Koi:
- User Guide - from first command to advanced usage
- Container Guide - Docker Compose, startup patterns, Kubernetes
Capability deep-dives:
- mDNS - Service Discovery
- Certmesh - Certificate Mesh
- DNS - Local Resolver
- Health - Endpoint Monitoring
- Proxy - TLS Termination
- UDP - Datagram Bridging
- Runtime - Container Lifecycle Adapter
- System - Daemon Lifecycle
- Embedded - Rust In-Process
Reference:
- Architecture - crate structure, boundaries, design
- HTTP API - all 60+ endpoints
- CLI Reference - every command and flag
- Wire Protocol - JSON protocol spec
- Ceremony Protocol - interactive flow engine
- Envelope Encryption - CA key protection
Decisions:
- Architecture Decision Records - why things are the way they are
Koi (鯉) are the fish that live in garden ponds. They're visible - they surface, they announce themselves by simply existing. You look into the pond and see what's there. That's service discovery: the network is the pond, the services are the koi. You peer in and see what's swimming.
The binary is koi. The crates.io package is published as koi-net because koi was already taken.
Koi is an orchestration wrapper - the heavy lifting happens in mdns-sd, a pure-Rust mDNS/DNS-SD implementation by @keepsimple1. Their library handles probing, conflict resolution, known-answer suppression, goodbye packets, cache flushing, and all the multicast plumbing that makes service discovery actually work. Koi just gives it a friendly front door.
Dual licensed under Apache-2.0 and MIT. See LICENSE-APACHE and LICENSE-MIT.
Free to use, embed, bundle, and redistribute, commercially or otherwise. Just link back to this project somewhere reasonable (a README, an about page, a comment in your manifest). That's it.
See CONTRIBUTING.md for development setup, code style, and contribution guidelines.