Sign inSign up
koppel logo

matumisoftware/koppel

By matumisoftware

•Updated 3 days ago

Share USB devices over the network: USB/IP with a web UI, pairing and TLS. amd64, arm64, arm/v6

Image
Networking
0

760

matumisoftware/koppel repository overview

⁠Koppel

Share USB devices over the network. Plug a device into one machine and use it on another.

Koppel speaks the standard USB/IP protocol and adds a web UI, sign-in and encrypted transport around it. A machine runs as a server (shares its devices), a client (attaches them) or both. Clients find servers on the local network and pair by typing a code, so nobody copies secrets around.

⁠Tags

TagWhat
0.2.0The current release, rewritten in Rust. Pin this one
latestThe newest release
0.1.2, 0.1.1, 0.1.0The earlier .NET releases

0.2.0 and latest are for linux/amd64, linux/arm64 and linux/arm/v6 (32-bit Raspberry Pi OS, the Pi Zero included). The image is about 4.5 MB compressed, on distroless/static. A 0.2.0 machine and a 0.1.x machine cannot link, so update both ends; pairings and settings carry over.

⁠Run it on Linux

The host needs the kernel's USB/IP modules (usbip-host to share, vhci-hcd to attach). The repository's prepare-host.sh installs Docker on Debian and Ubuntu and loads the modules now and at every boot:

wget https://raw.githubusercontent.com/matumi-software/koppel/main/src/installer/docker/prepare-host.sh
sudo bash prepare-host.sh

Then start Koppel with this docker-compose.yml:

name: koppel

services:
  koppel:
    image: matumisoftware/koppel:0.2.0
    network_mode: host    # clients find the server by broadcast, which does not cross Docker's bridge
    volumes:
      - koppel:/koppel
    user: "0"             # sharing and attaching devices write to /sys
    privileged: true
    restart: always

volumes:
  koppel:
docker compose up -d

Open https://<machine>:5240 within 10 minutes, accept the certificate warning (Koppel makes its own certificate), set the admin password and choose the role. After 10 minutes, restart the container to open setup again.

To pair a client: on the client open Configuration, press Pair next to the server, and approve the six-digit code on the server's Clients page.

⁠Ports

PortWhat
5240 TCPThe web UI, and everything other Koppel machines do: tokens, pairing, the device list and USB traffic, all over HTTPS
5240 UDPFinding servers on the local network

⁠Data

Settings, the server's certificate, registered clients and the encryption keys live in the volume at /koppel, not in the image, so an upgrade keeps them. To upgrade, change the tag and run docker compose pull && docker compose up -d. Upgrading from 0.1.x converts the files on first start.

Paths__KeyCertificate is no longer read: a 0.1.x volume that used it starts fresh, and its clients pair again.

⁠Settings

Set them as environment variables. The most useful:

VariableDefaultWhat
Ui__AllowFromlanWho may open the UI: local (this machine), lan (the local network) or any
Ports__NetworkPut what other Koppel machines do on a port of its own, so the UI can stay on 5240 alone
Discovery__Portthe network portThe UDP port for finding servers
Usb__UpstreamWindows server only: the usbipd-win address to share devices from
Usb__AttachTimeoutSeconds20How long an attach may take before it fails with a reason

⁠Docker Desktop on Windows

A container cannot reach Windows' USB devices itself, so on Windows Koppel works next to a USB/IP driver on the host: usbipd-win for a server, usbip-win2 for a client. The repository has a compose file for each (src/installer/docker/docker-compose.windows-server.yml, docker-compose.windows-client.yml), and docs/windows.md walks through them. For a Windows client, the native installer from the releases page is simpler.

⁠Forgot the password

docker compose run --rm koppel --reset-password

Then open the UI within 10 minutes and set a new one.

⁠Health

The image has a health check (koppel --healthcheck, which asks /healthz). Plain Docker only reports an unhealthy container; it does not restart it.

⁠Known limits

  • The container is privileged and runs as root, because sharing and attaching write to /sys.
  • The UI's certificate is self-signed. Check its SHA-256 fingerprint (shown under Clients) before you accept the warning on a network you do not trust.
  • Not yet run on real hardware with 0.2.0: a Linux client, a Windows server through usbipd-win, and a Raspberry Pi. Reports are welcome: https://github.com/matumi-software/koppel/issues/42⁠
  • Printers are untried. Webcams do not stream from a Linux server to a Windows client yet.
  • A client connects to one server at a time.

Report security problems privately: https://github.com/matumi-software/koppel/security/advisories/new⁠

Tag summary

Content type

Image

Digest

sha256:3242a2b52…

Size

4.3 MB

Last updated

3 days ago

docker pull matumisoftware/koppel