Support

What to send us, so a bug report gets an answer instead of a questionnaire

Write to [email protected]. There is no ticket system, no forum and no account — it is an email address, and a person reads it.

Kestrel talks to your equipment on your network, and we can see none of it. Nothing is reported to us, because there is nowhere for it to be reported to. That makes your description the only evidence there is, so the lists below are what turns “it doesn't work” into something that can actually be found and fixed.

1. Worth checking first

Not to send you away — the address is at the top and you are welcome to use it — but these account for a good share of what gets reported, and each of them is faster than waiting for a reply.

Can you reach the device yourself? Open its own web interface in a browser, at the same address and port you gave Kestrel. If that fails, the problem is between you and the device, and Kestrel cannot get past it either.
Are the credentials the device's own? There is no Kestrel account. The username and password belong to your camera, NVR or controller — and for UniFi Protect they must be a local account, because a cloud account requires two-factor that the app cannot complete.
Is it on the same network? Kestrel is a LAN client. It does not use any vendor's cloud relay — no Reolink P2P/UID, no UniFi cloud — so a device it cannot route to is a device it cannot see.
Is it already a known limitation? The limitations list and the FAQ cover the common surprises: no two-way audio, no continuous recording, and the Roku's snapshot mode not being real video unless the HLS add-on is in front of it.
Is it already a known issue? The known issues page lists the faults we have seen, including the ones that turn out to be the equipment rather than Kestrel — a Reolink NVR that will not produce snapshots for certain cameras is the current example, and it looks exactly like a broken camera wall.
Is it one of the systems nobody has run yet? See section 7 — those reports are wanted, and they need slightly different things.

2. What every report needs

Five things, whichever app you are using. Everything after this section is detail on top of them.

Tell us	Why it matters
Which app, and its version	Kestrel for Linux, Kestrel for Roku, or the Kestrel Screensaver — they are separate programs that share no code, and a fix in one is not a fix in the other
What you did, what happened, what you expected	In that order, in plain words. “The wall went black when I pressed OK on camera 3” is a bug report; “the Roku app is broken” is not
The exact message on screen	Word for word, or a photo. Kestrel's failures are written to name the thing that failed, so the wording is often the whole diagnosis
Which system, model and firmware	Reolink, Frigate, ZoneMinder, QNAP QVR or UniFi Protect — plus the model and firmware version, from the device's own interface. Capability differences between firmware revisions are the single most common cause of “it works for you and not for me”
Whether it ever worked	Always been like this, or started after something — an app update, a firmware update, a new camera, a network change. If you know when, say when

Two more that cost you a sentence and save a round trip: how many devices and cameras you have added, and whether it happens every time or only sometimes. An intermittent fault and a reproducible one are hunted differently.

3. Kestrel for Linux

The version, and where things are

The ⋯ overflow button in the toolbar opens About Kestrel, which gives the version, the build date, the config path, the media folder, and which password store is in use. A screenshot of that dialog answers most of this section at once. From a terminal:

kestrel --version
Kestrel 0.1.0 (built 2026-08-11)

Which build, and what it is running on

The AppImage or the tarball — they behave differently enough to matter, particularly around system libraries.
Your distribution and version, your desktop environment, and whether you are on Wayland or X11.
For anything visual — tearing, a black tile, a window that will not draw — your GPU and driver.

The log

Kestrel logs to standard error, so start it from a terminal and the log appears there. By default it logs its own activity at info level and keeps third-party libraries quiet. RUST_LOG raises that, and kestrel=debug is almost always the level worth sending:

# installed from the tarball
RUST_LOG=kestrel=debug kestrel 2>&1 | tee ~/kestrel.log

# or the AppImage
RUST_LOG=kestrel=debug ./Kestrel-0.1.0-x86_64.AppImage 2>&1 | tee ~/kestrel.log

Reproduce the fault, quit, and send ~/kestrel.log — or, if it is long, the last hundred lines and everything around the failure. RUST_LOG=debug without the kestrel= prefix turns on every library too, including a D-Bus frame per keyring call; it is occasionally useful and mostly noise.

Session tokens and RTSP credentials are redacted from every log line and error message, so a log is safe to send in that respect. It will still contain your device addresses, usernames and camera names — replace them if you would rather we did not have them. It never makes a report unusable to write NVR-ADDRESS instead of the real one, as long as you do it consistently.

Configuration, if the problem is about devices or settings

This prints what Kestrel thinks it has been told, which is frequently not what you meant to tell it:

kestrel --check-config

It reports the config path, whether a system keyring was found or the file fallback is in use, the media folder, the grid and warm-stream settings, and one line per device — address, port, username, whether a password was loaded, and the cached channel count. Passwords are never printed, only loaded or MISSING; a MISSING there is usually the whole answer to “it stopped logging in”. Addresses and usernames are printed, so redact them if you want to.

Connection failures, if you are on Reolink

There is a one-shot command-line path that connects, logs in and reports what it found, without the interface in the way. It is Reolink only — the other systems are reachable through the app, not this command:

KESTREL_PASSWORD='…' kestrel 10.0.0.50 --user viewer

On success it prints the model, firmware, channel count, which channels are online and what each supports, then fetches a snapshot from the first one. On failure it prints FAILED: and the reason. Either output is worth pasting in — it separates “the device refused us” from “the app mishandled the answer”, which are different bugs. --port, --rtsp-port and --https are there if your device is not on the defaults.

4. Kestrel for Roku

A Roku channel installed from the Channel Store has no log we can ask for and no file you can send. What it has instead is what is on the television, so the screen itself is the evidence here — a photo of it is genuinely the most useful thing you can attach.

The television

Roku model and Roku OS version, from Settings → System → About on the Roku itself. Hardware generations differ enormously in what they can decode and how much memory a wall of cameras may use, and this is the first thing we look at for anything about performance or a wall that will not fill.
How it is connected — wired or wireless, and if wireless, the signal strength from Settings → Network → About. A wall of cameras is a great deal of traffic to ask of a weak connection.
When you installed or last updated the channel. The channel does not display a version number on screen, so a date is what pins down which build you have.
Whether the screensaver is affected too. It reads the settings the app wrote and shares nothing else, so “both” and “only one of them” point in different directions.

What the channel was doing

Snapshot mode or HLS mode, and if HLS, whether it is Kestrel HLS or a restreamer of your own — go2rtc, MediaMTX, Frigate — and how that is configured. For the add-on there is a section of its own below; the channel's setup notes are here.
How many cameras are on the wall, and whether the fault is on all of them, one of them, or one particular camera wherever it lands. Wall size changes both the layout and the stream quality the channel asks for.
Which screen — the wall, a single camera full screen, the settings screen, follow mode, the weather screen or the radar.
For a problem adding a device, the status line under the settings form. It says what it is doing and what came back, and that line is the closest thing the channel has to a log.

Two built-in tests worth running before you write

Both live in the channel's settings, and both narrow a fault down considerably:

Identify this system asks the address what it is running, without any credentials. “Looks like …” means the television can reach it and it answered as expected — which moves the problem to the login. “Could not tell what that address is running” means it could not, and the address, the port or the network is where to look. Send us the sentence it printed.
Connect attempts the login itself, and reports what came back.

If nothing helps and you want to start clean, Forget saved settings clears the stored devices and credentials. Tell us if you have done it, and what changed — that is a data point rather than a lost one.

5. Kestrel HLS

The add-on is the one part of Kestrel with a real log, so a report about HD video on the television is usually answered from its panel rather than from the TV. Send section 4 as well if the fault is anything the channel does — falling back to snapshots is a fact about both halves.

What the panel already knows

Nearly everything worth asking for is on the camera's own row, so a screenshot of the row while the fault is happening carries most of a report by itself:

What state it is in — starting, live, failed — and what it says instead of a reading. Starting and then failed points at the camera; live while the television refuses the stream points at us, and is worth reporting for exactly that reason.
Whether it is copying or re-encoding, and what it found in the stream: the video codec, whether there is sound and in what codec, and whether it fell back to the camera's other stream.
The latency it reports, and whether it says the camera's keyframe interval is setting the floor. That sentence answers most "why is the picture so far behind" questions before they are asked. Why the picture is behind.
The damaged tag and its count, if it has one. Whether the count climbs while copying or only while re-encoding says whether to look at the network or at the machine.
What "What is it serving?" printed. It produces the stream, reads it back and reports the codec, profile, level, size, pixel format, frame rate and sound track actually going out. For anything the television calls an unsupported format, that output is the report.

The add-on log

From the add-on's page in Home Assistant, under Log. Set the log level to debug on the options tab first if the fault can be reproduced on demand. Camera passwords are redacted from every line and every API response, which is what makes the log safe to send — addresses and usernames are not, so remove those if you would rather they did not travel.

And the shape of the setup

The add-on version, from the panel, and what it runs on — the machine and its architecture. Whether an armv7 machine can re-encode at all is a genuine unknown, so that detail is not idle curiosity.
How many cameras are registered, how many are being watched at once, and how many of them are re-encoding rather than being copied.
Whether the camera is H.264 or H.265 on the stream in use, and whether the television is a 4K model. Most of what looks like an add-on fault is the H.265 problem.
Whether "Check the add-on now" on the television succeeds, and what it printed. That separates a pairing or network problem from a streaming one.

6. Weather and radar

On both apps, off by default, and the one part of Kestrel that leaves your network — so it fails in its own ways. If your report is about the weather strip, the weather screen or tab, or the radar, tell us which app and add:

Which source — weather.gov, or a WeeWX server of your own — and the setting that goes with it: the ZIP code you entered, or the address you gave it.
What it says instead of a reading. Both apps report the failure in words rather than going blank: on Roku, Fetch the weather now in the weather settings; on the desktop, the reason appears in the strip and at the top of the Weather tab. The sentence with the reason in it is the one we need.
For a WeeWX server, the document itself. Open its address in a browser and send the JSON, with anything identifying removed. If a field is missing or shaped unexpectedly, that shows it immediately.
For the radar, the range and basemap you have set — and on Roku, whether it is on the wall, its own screen or both.
For anything about an alert, what the alert was and where it was published — that path has had very few real alerts to draw.

None of the weather layout has ever been rendered on a television. It is described in full on the Roku page, and it means a layout fault there is more likely than elsewhere in the channel — and more useful to hear about. A photograph of a weather or radar screen that looks wrong is worth several paragraphs. The desktop's has been checked on screen, so the same caveat does not apply to it.

7. If you run an untested system

Only Reolink is verified continuously, on real hardware, on both clients. The Roku channel has logged in to a real UniFi Protect controller and drawn a wall, and nothing past that is proven. Frigate, ZoneMinder and QNAP QVR were written from published API documentation and have never been run against an actual install — and on the desktop client, neither has UniFi. The three states are set out here.

So if you run one of those, you are very likely the first person to, and we would rather hear about it than not — including when it simply works, which is information we currently have no way to get. Two things make such a report far more useful:

On the Roku channel, turn on Untested features first, at the bottom of Settings. Those three systems are marked untested in the picker and refused until it is on, so without it you will not get as far as trying.

Your install's shape. The path prefix for ZoneMinder, whether Frigate has authentication enabled and where its go2rtc lives, QVR Pro versus QVR Elite. The guesses in each of those places are exactly what is most likely wrong.
How far it got. Login, camera list, wall, live video, controls — the point at which it stopped tells us which assumption broke.

8. What not to send

We do not need these to help, and would rather not hold them. This mirrors the privacy policy, which says the same thing.

Passwords or credentials, for anything, ever. Nothing in a diagnosis requires them.
Camera footage. If a screenshot or a photo of the screen is the point, crop or blur anything — people especially — that you would not want a stranger to see. A picture of a broken layout does not need to be a picture of your driveway.
Anything that reaches your network from outside it. We will never ask for remote access, a port forward or a tunnel to your NVR, and you should treat any message that does as not being from us.
Payment details or receipts. Roku handles the money; we have no access to the transaction and nothing to do with it.

Real device addresses are your call. They are helpful and they are also yours — a consistently redacted log is fine.

9. What we cannot help with

Purchases and refunds for the Roku channel. Roku is the merchant: it takes the payment, issues the receipt and owns the refund path. The Terms explain where to go. We never receive your payment details and cannot see, verify or reverse a purchase.
Your camera hardware, its firmware, or its own apps and cloud services. Kestrel is a client for equipment other people make. If the device's own interface has the same problem, its manufacturer is who can fix it.
Footage taken by somebody else's cameras. We have no access to any footage anywhere, and no ability to act on it. That is set out in the privacy policy.
Recovering anything deleted. There is no copy, cache or backup of your recordings on our side, because there is no our side.

10. What to expect back

Kestrel is a small independent project, not a company with a support desk. Mail is read and answered by a person, in reasonable time, and there is no service level to promise beyond that. If you have not heard back in a week, send it again — mail does occasionally go missing, and a reminder is not a nuisance.

A useful answer is sometimes “that is a limitation, here is why, and here is where it is already written down”. Where a report turns out to be a real defect, what usually happens next is a request for one specific thing — a log line, a firmware version, the output of one of the commands above. Sending the material in the templates below up front skips that round entirely, which is the whole reason this page exists.

Feature requests are welcome and are treated honestly: they will be answered, and often the answer is no. What the apps deliberately do not do, and why, is on the limitations list.

11. Copy-and-paste templates

Paste one of these into your email and fill it in. Nothing here is required — a report with half of it is still far better than a report with none of it.

Kestrel for Linux

What happened:
What I expected:
How to reproduce it:
Happens every time / sometimes:

Kestrel version:            (⋯ → About Kestrel, or kestrel --version)
Installed from:             AppImage / tarball
Distribution and version:
Desktop environment:        (and Wayland or X11)
GPU and driver:             (only for display problems)

System:                     Reolink / Frigate / ZoneMinder / QNAP QVR / UniFi Protect
Model and firmware:
Number of devices/cameras:
Ever worked before:         no / yes, until …

Exact message on screen:

Log attached:               RUST_LOG=kestrel=debug, addresses redacted

Kestrel for Roku

What happened:
What I expected:
How to reproduce it:
Happens every time / sometimes:
Screen it happens on:       wall / full screen / settings / follow / weather / radar

Roku model and OS version:  (Settings → System → About)
Network:                    wired / wireless (signal strength)
Channel installed/updated:  approximate date
Screensaver affected too:   yes / no

System:                     Reolink / Frigate / ZoneMinder / QNAP QVR / UniFi Protect
Model and firmware:
Video mode:                 snapshot / HLS (Kestrel HLS add-on / which restreamer)
Cameras on the wall:
Affects:                    all cameras / one camera / one position

"Identify this system" said:
Status line said:

Photo of the screen attached: yes / no

Kestrel HLS

What happened:
What the camera's row said:  starting / live / failed, and the message
How to reproduce it:
Happens on:                  every camera / one camera / only when several are watched

Add-on version:
Runs on:                     machine and architecture (amd64 / aarch64 / armv7)
Cameras registered:          total, and how many watched at once
This camera:                 copied / re-encoded, main / sub stream
Video and sound found:       (as reported on the row)
Latency reported:            and whether it says the keyframe interval sets the floor
Damaged count:               climbing while copying / while re-encoding / not at all

Television:                  Roku model, and 4K or 1080p
"Check the add-on now" said:
"What is it serving?" said:

Log attached:                add-on page → Log, level debug

Then send it to [email protected]. Thank you for bothering — a report that arrives is worth more than a fault suffered quietly.