Skip to content
filirndPublic

About

A desktop app for Tapo

Resources

Stars

18 stars

Watchers

1 watching

Forks

Repository files navigation

Topo logo

Topo

Desktop app for Tapo camera
View and control your Tapo cameras from a clean Linux or Windows desktop app.

Linux Windows Tapo Cloud streaming Experimental status

Topo camera dashboard with privacy-blurred camera previews

Topo is a standalone Linux and Windows desktop application for viewing and controlling Tapo cameras through the Tapo cloud account.

Official website: filirnd.github.io/topo

It uses Tapo's cloud relay and does not require RTSP, port forwarding, a VPN, or direct access to the camera's home network. The application opens a native desktop window: GTK/WebKitGTK on Linux and Electron on Windows. No browser needs to be opened manually.

Experimental: the cloud integration relies on undocumented Tapo endpoints and may need updates if Tapo changes its service.

At a glance

Connection Tapo cloud relay — no RTSP, port forwarding, VPN, or camera LAN access
Desktop shell GTK 3 + WebKitGTK 4.1 on Linux; Electron on Windows
Media pipeline Cloud relay decoded by FFmpeg and shown in the desktop UI
Authentication Tapo account login with MFA and reusable session
Controls Privacy toggle, relay check, pan/tilt, SD recordings, and per-camera fullscreen

Features

  • View multiple Tapo camera live streams in the same window.
  • Cloud relay connection check for each camera.
  • MFA login through the Tapo app notification or email code.
  • Session reuse across launches, so MFA is not requested every time.
  • Logout support that clears the saved session.
  • Per-camera privacy mode toggle.
  • Pan and tilt for compatible cameras with compact control panel.
  • Per-camera fullscreen mode.
  • Stream loading state, error state, and retry button.
  • Responsive layout for different window sizes.
  • Play complete recording videos from the camera SD card.
  • Download selected SD-card recordings as MP4 files.

Live audio can be enabled independently for each camera after an explicit user click. When enabled, the live audio volume can be adjusted independently for each camera.

Tested cameras

The following model has been tested with Topo:

Model Live video Privacy mode Pan & tilt
Tapo C200 Yes Yes Yes

SD-card recording search and cloud playback have also been tested on two Tapo C200 cameras with local recordings available. SD-card playback, audio, and MP4 downloads are supported for the tested recordings.

More testers are welcome. If you use another Tapo camera model, please open an issue with the model name, firmware version, and which features work. Do not include account credentials, session tokens, or private camera footage.

Current limitations

  • SD recordings include camera audio when the camera relay provides it.
  • Live audio requires an explicit click because desktop WebKit/WebView browsers block autoplay with sound.
  • Desktop motion/event notifications are not currently implemented.
  • Snapshots are not currently implemented.
  • Pan/tilt is available only for cameras supported by the Tapo cloud account.
  • A working Internet connection and an active Tapo account are required.

Requirements

Linux

  • Linux desktop environment with GTK 3.
  • Python 3.
  • WebKitGTK 4.1.
  • FFmpeg.

The installer supports automatic dependency detection and installation on Ubuntu/Debian and Fedora/RHEL. On other distributions, install the requirements manually before running the installer.

On Fedora, FFmpeg may require an additional multimedia repository such as RPM Fusion, depending on the system configuration.

Windows

The Windows installer includes the Topo backend and FFmpeg. End users do not need to install Python, Node.js, GTK, WebKitGTK, or FFmpeg separately. A Tapo account with access to the cameras is required on both platforms.

Linux installation

Clone the repository and run the Linux installer:

git clone https://github.com/filirnd/topo.git
cd topo
chmod +x linux/install.sh linux/uninstall.sh
./linux/install.sh

The installer:

  1. checks Python 3, GTK 3, WebKitGTK 4.1, and FFmpeg;
  2. identifies Ubuntu/Debian or Fedora/RHEL when dependencies are missing;
  3. asks for confirmation before using apt or dnf;
  4. installs the application under the user's local data directory;
  5. creates a desktop launcher and installs the Topo icon.

After installation, launch Topo - desktop app for Tapo camera from the desktop application menu.

To uninstall:

./linux/uninstall.sh

Windows installation

Download the latest Windows installer from the GitHub Releases page, then run the .exe installer. Topo installs per user and creates a desktop shortcut and a Start Menu entry.

Topo is currently distributed without a code-signing certificate from a Windows-trusted publisher. Windows may therefore show a Windows protected your PC or Unknown publisher warning. Before continuing, make sure the installer was downloaded from the official Topo GitHub repository. In the SmartScreen dialog, select More info and then Run anyway if you trust the source.

The Windows installer is x64. It includes the Topo backend and FFmpeg, so end users do not need to install Python, Node.js, or FFmpeg separately.

Build the Windows installer yourself

If you do not want to run a prebuilt installer, inspect the source and build it locally. The repository provides both a Linux/Docker build and a native Windows PowerShell build:

On Linux, with Docker installed:

./windows/build-local.sh

On Windows, with Python 3.12 and the current Node.js LTS release installed:

powershell -ExecutionPolicy Bypass -File .\windows\build-local.ps1

Both commands write the installer to windows/out/. Full build requirements and troubleshooting notes are in windows/LOCAL_BUILD.md.

Maintainer release flow

The Windows workflow also publishes the installer as a GitHub Release when a semantic version tag is pushed. For example:

git tag v0.1.4
git push origin v0.1.4

The workflow builds the installer, aligns the Windows app version with the tag, generates SHA256SUMS.txt, and attaches both files to the release. A normal push to main only runs the build and stores the result as a temporary Actions artifact; it does not create a release.

Flatpak distribution

Topo can also be distributed through a self-hosted Flatpak repository on GitHub Pages. This provides a clickable .flatpakref installer and normal Flatpak updates without requiring a Flathub submission.

The public installation link is:

https://filirnd.github.io/topo/io.github.filirnd.topo.flatpakref

Install directly from the published repository with Flatpak:

flatpak install --user https://filirnd.github.io/topo/io.github.filirnd.topo.flatpakref

The .flatpakref can also be downloaded and opened with GNOME Software when Flatpak support is enabled. The repository is added automatically and future application updates can be installed with:

flatpak update --user

The Flatpak package is cloud-only and needs network access, but it does not need RTSP, Tailscale, a Raspberry Pi, or access to the home LAN.

Login and session storage

On the first launch, enter the Tapo account credentials. If MFA is required, choose either the Tapo app notification or the email verification code.

The application stores a session token at:

Linux:   ~/.local/state/tapo-cloud-probe/session.json
Windows: %LOCALAPPDATA%\Topo\state\session.json

The password is not stored. Use Logout to clear the session and require a new login on the next launch.

To force a fresh login when launching the installed wrapper manually:

~/.local/share/tapo-cloud-viewer/run-tapo-cloud-viewer --fresh-login

Security notes

  • Treat session.json as a credential and never publish it.
  • Do not commit account passwords, session tokens, or private camera data.
  • The app adds the TP-Link public cloud root certificates used by the official Tapo Android client to the normal system trust store. TLS certificate validation and hostname verification remain enabled; the app does not provide a TLS verification bypass.
  • The local HTTP service is bound to 127.0.0.1 and is used only by the desktop application window.
  • The Windows build is not code-signed yet; verify its source before bypassing the SmartScreen warning.

Development

Run the desktop shell directly from the repository after installing the system dependencies:

python3 tapo_desktop.py

Useful options:

--fresh-login    force a new Tapo login and MFA flow
--port PORT      use a specific local HTTP port (0 selects a free port)

AI Full Disclosure

This software was developed with substantial assistance from AI coding agents, with humans leading the ideas, architecture decisions, testing, and debugging. We state this openly because AI assistance shaped how the project was built. If you are not comfortable using software developed with AI assistance, this project may not be for you.

The final responsibility for the code, its behavior, and its security remains with the project author. The Tapo cloud integration also relies on undocumented endpoints and may require maintenance when the upstream service changes.

License

Topo is released under the MIT License.

About

A desktop app for Tapo

Resources

Stars

18 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages