kaya-go/README.md

Kaya

Introduction

Kaya is an early-stage implementation of a fully end-to-end encrypted IPv6 network. It is lightweight, self-arranging, supported on multiple platforms and allows pretty much any IPv6-capable application to communicate securely with other Kaya nodes. Kaya does not require you to have IPv6 Internet connectivity - it also works over IPv4.

Supported Platforms

Kaya works on a number of platforms, including Linux, macOS, Ubiquiti EdgeRouter, VyOS, Windows, FreeBSD, OpenBSD and OpenWrt.

Please see our Installation page for more information. You may also find other platform-specific wrappers, scripts or tools in the contrib folder.

Building

If you want to build from source, as opposed to installing one of the pre-built packages:

1. Install Go (requires Go 1.22 or later)
2. Clone this repository
3. Run ./build

Note that you can cross-compile for other platforms and architectures by specifying the GOOS and GOARCH environment variables, e.g. GOOS=windows ./build or GOOS=linux GOARCH=mipsle ./build.

Running

Generate configuration

To generate static configuration, either generate a HJSON file (human-friendly, complete with comments):

./kaya -genconf > /path/to/kaya.conf

... or generate a plain JSON file (which is easy to manipulate programmatically):

./kaya -genconf -json > /path/to/kaya.conf

You will need to edit the kaya.conf file to add or remove peers, modify other configuration such as listen addresses or multicast addresses, etc.

Run Kaya

To run with the generated static configuration:

./kaya -useconffile /path/to/kaya.conf

To run in auto-configuration mode (which will use sane defaults and random keys at each startup, instead of using a static configuration file):

./kaya -autoconf

You will likely need to run Kaya as a privileged user or under sudo, unless you have permission to create TUN/TAP adapters. On Linux this can be done by giving the Kaya binary the CAP_NET_ADMIN capability.

Documentation

Documentation is available on our website.

• Installing Kaya
• Configuring Kaya
• Frequently asked questions
• Version changelog

Extended Features in This Repository

This repository includes a substantial set of enhancements on top of the baseline Kaya behavior, focused on performance, operability, observability, and operator UX.

1) Operator Dashboard (Built-in HTTP UI)

A built-in web dashboard is available directly from the daemon to monitor and manage node state.

• Live runtime telemetry for:
  • node/self identity and routing metadata,
  • peer links and per-peer health,
  • session/flow activity,
  • path and tree information.
• Peer control actions from the UI (e.g. disconnect/traffic control via the daemon APIs).
• Optional authentication for the private dashboard listener.
• Public read-only dashboard mode (--public-interface) for safe external observability exposure.
• Real-time bandwidth visualization and rate rendering in human units (Mbit/s), including directional indicators.
• Responsive, overflow-safe layout so long URIs/IP addresses remain contained and readable.

2) Runtime Control and Safety Hardening

The runtime now provides stronger operator controls for CPU/thread behavior and process hardening:

• --threads controls scheduler parallelism (GOMAXPROCS) explicitly.
• --max-threads provides an additional hard cap for runtime OS threads.
• --sandbox enables Linux hardening measures early in runtime startup:
  • no-new-privileges,
  • non-dumpable process mode,
  • core-dump suppression.

These options are intended for predictable behavior on constrained systems and for hardened production deployments.

3) Colorized, High-Signal Terminal Logging

Interactive stdout logs are rendered with contextual colorization to improve readability and triage speed:

• different color classes for errors, warnings, link lifecycle, addressing/interface messages, and sandbox messages,
• improved per-line rendering for TTY operation,
• better at-a-glance operator diagnostics during startup and runtime events.

4) Admin API Extensions for Traffic Control

The admin control surface includes enhanced peer traffic operations:

• setPeerTraffic support to toggle whether traffic is routed via specific peers,
• stricter boolean parsing/validation in control requests,
• integration with dashboard and CLI control workflows.

5) kayactl UX and Topology Visibility Improvements

CLI output and control ergonomics were expanded:

• improved peer listing with a direct Remote endpoint/host view,
• significantly clearer tree/topology presentation with hierarchical formatting,
• tighter integration with peer traffic control operations.

6) Core Performance Optimizations

Multiple datapath-adjacent and control-path optimizations were added to reduce CPU and allocation pressure without changing protocol semantics:

• periodic link average updates moved to persistent ticker-style processing (reduced timer churn),
• peer snapshot collection optimized with better preallocation and reduced repeated work,
• optimized inbound allowed-key authorization path using faster lookup strategy,
• reduced atomic overhead in hot accounting paths by skipping zero-byte updates,
• debug protocol response assembly/lifecycle improvements to reduce transient allocations and bound payload behavior,
• URI parsing and formatting optimizations in CLI/control surfaces.

7) Transport and Dialing Efficiency Enhancements

Connection setup paths were tuned for performance and reliability across transports:

• better TCP source-interface handling with short-lived interface metadata caching,
• improved address selection and error behavior in dial suitability checks,
• WS/WSS transport setup refinements to reduce repetitive per-dial overhead,
• QUIC dialing/configuration improvements for throughput-oriented behavior and lower overhead in this usage profile,
• correctness fixes to ensure intended TLS configuration usage in QUIC dial paths.

8) Process-Model and Platform Behavior Tightening

Additional reliability and deployment refinements include:

• stronger single-process behavior expectations in runtime paths,
• FreeBSD TUN setup behavior tightened to return direct ioctl failures instead of shelling out to external fallback tooling,
• clearer startup/runtime wiring for dashboard lifecycle and shutdown handling.

9) Practical Outcome

Taken together, these enhancements provide:

• better operator visibility (dashboard + improved CLI),
• stronger runtime control (--threads, --max-threads, sandboxing),
• lower operational overhead in frequent control/network paths,
• improved day-2 usability for debugging, monitoring and peer management,
• preserved core functionality with a focus on safer and faster default operation.

Communities

A number of IRC communities exist, including the #kaya IRC channel on libera.chat and various others on Kaya-internal IRC networks.

License

This code is released under the terms of the LGPLv3, but with an added exception that was shamelessly taken from godeb. Under certain circumstances, this exception permits distribution of binaries that are (statically or dynamically) linked with this code, without requiring the distribution of Minimal Corresponding Source or Minimal Application Code. For more details, see: LICENSE.