Share USB devices over the network: USB/IP with a web UI, pairing and TLS. amd64, arm64, arm/v6
760
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.
| Tag | What |
|---|---|
0.2.0 | The current release, rewritten in Rust. Pin this one |
latest | The newest release |
0.1.2, 0.1.1, 0.1.0 | The 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.
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.
| Port | What |
|---|---|
| 5240 TCP | The web UI, and everything other Koppel machines do: tokens, pairing, the device list and USB traffic, all over HTTPS |
| 5240 UDP | Finding servers on the local network |
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.
Set them as environment variables. The most useful:
| Variable | Default | What |
|---|---|---|
Ui__AllowFrom | lan | Who may open the UI: local (this machine), lan (the local network) or any |
Ports__Network | Put what other Koppel machines do on a port of its own, so the UI can stay on 5240 alone | |
Discovery__Port | the network port | The UDP port for finding servers |
Usb__Upstream | Windows server only: the usbipd-win address to share devices from | |
Usb__AttachTimeoutSeconds | 20 | How long an attach may take before it fails with a reason |
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.
docker compose run --rm koppel --reset-password
Then open the UI within 10 minutes and set a new one.
The image has a health check (koppel --healthcheck, which asks /healthz). Plain Docker only reports an
unhealthy container; it does not restart it.
/sys.Report security problems privately: https://github.com/matumi-software/koppel/security/advisories/new
Content type
Image
Digest
sha256:3242a2b52…
Size
4.3 MB
Last updated
3 days ago
docker pull matumisoftware/koppel