eufy_security: a Home Assistant bridge to Eufy cameras and doorbells

The repository is frozen and points somewhere else

The first thing in this README is a notice, and it is not a formality. It says to check the new implementation and that this repository will not be updated any further, and it links two projects, a Home Assistant add-on repository and a second repository for the SDK work.

That single line changes how the whole article should be read. The code in this repository is a frozen snapshot of an approach that worked, not a project that is being developed. The releases tell the same story from the other side. The tags are v8.2.3 and v8.2.4, both published on 2026-04-09, and v8.2.5 on 2026-09-23, and the last push to the repository was on 2026-09-23 as well.

What remains here is still worth understanding, because the arrangement is unusual and the constraints it imposes on a user's account are the part most likely to surprise somebody. The repository is a Home Assistant custom integration written in Python, MIT licensed, and its layout is small, with a custom_components/ directory holding the integration itself, a hacs.json file for the Home Assistant Community Store, a LICENSE file and the README.

The integration is not part of Home Assistant Core, so it has to be installed as a custom integration, either by downloading the files and copying them in, or through HACS, and the README walks through the HACS route.

The device coverage is broad. The description names cameras, home base stations, doorbells, motion sensors and contact sensors, and the list of supported or known working devices is not maintained here but pointed at, in the readme of the client library that does the actual talking to the devices.

The add-on imitates the mobile app

The section titled how is this working explains the architecture, and it is the key to understanding the whole design.

The original author of the client library built eufy-security-ws using eufy-security-client to imitate mobile app and web portal functionalities, and that service was then wrapped as a Home Assistant add-on so it can be used from the add-ons page. So there are two moving parts. The add-on holds a WebSocket connection to the Eufy cloud, presenting itself as a client, and it speaks the same protocol the phone app speaks. The Home Assistant integration talks to that add-on locally and turns the events into entities and services.

The reason for the imitation is not a design preference but an interoperability fact. The Eufy cloud does not offer a public API for third party clients, so a Home Assistant integration cannot simply ask it for camera status, and the only protocol available is the one the app uses. Emulating the app is the workaround, and it explains why the add-on needs account credentials at all.

The add-on asks for five things: an email address, a password, a country code, an event duration in seconds and a trusted device name. None of them is optional, and the last three have consequences that are not obvious from the form.

There is also a runtime cost to the arrangement. The add-on heavily relies on push notifications, so you must enable all kinds of push notifications, motion detected, person detected, lock events, alarm events and so on, in the mobile app. Those notifications are not user based but device based, so after enabling them your main account will probably be bloated with many push notifications, and on Android there is a setting to disable specific notifications, which the README suggests you use.

Every start of the add-on logs your other sessions out

This is the requirement that most affects how you set up your account, and it deserves to be read twice.

Every time the add-on is started, it forces all other sessions to log off. So you must create a secondary account and share your home and your devices with that secondary account, including admin rights, and you must use the secondary account credentials on the add-on page. You also have to log in once to the Eufy mobile app with this secondary account, to be sure the devices are available to it.

In other words, the design asks you to treat the integration as a separate device on your account rather than as your phone. The secondary account with admin rights is the unit of trust, and the main account stays clean.

The other configuration field, country code, is described as very crucial to connect to correct regional servers. The README gives the reason: if your main account is set up in the US and you log in to your secondary account with a DE country code, your device data would not be found in the EU servers. The reference given is the ISO 3166-1 alpha 2 code, so the field is a two letter country code and it must match the region where the account was created.

The event duration in seconds is simpler but just as important. It corresponds to how long the entities in Home Assistant stay active, and the example given is that when the camera notices a person, the add-on receives a push notification from Eufy, the integration activates the person detected sensor, and that sensor stays on for the configured duration. So it is a timeout on the entity state, and it determines how long a motion event remains visible to your automations.

The trusted device name is how you find it in two factor authentication

The fifth field has a narrow purpose that is easy to skip.

The trusted device name is a required identifier for Eufy systems to record the add-on as a mobile client, so you can differentiate the connection from this add-on in the multi factor authentication, two factor authentication, page. In practice it means the add-on shows up in your account's list of trusted devices under a name you chose, and when you are looking at a login prompt or a device list, you can tell which entry is the integration and which one is your phone.

That matters because of the session invalidation described earlier. Every start of the add-on forces the other sessions out, and a name that is recognisable is what stops you from locking yourself out of your own account while trying to work out which session to approve.

The three fields together, country code, event duration and trusted device name, are the practical configuration surface of this integration, and each of them exists because of a specific failure it prevents. The country code connects you to the right regional server and therefore to your devices, the event duration sets how long an event entity is active, and the trusted device name makes the add-on identifiable in the account's own security UI.

RTSP or a go2rtc conversion for the video

Video is the part of the integration with the most moving pieces, and the README splits the decision cleanly.

If your camera supports RTSP, Real Time Streaming Protocol, based streaming, the README expects you to have a more reliable stream, because generating the RTSP stream is the responsibility of the hardware and it is very much more reliable than peer to peer based streaming. There is no need to convert the incoming peer to peer bytes into an RTSP stream.

If your camera does not support RTSP, meaning there is no option for continuous or NAS recording in the camera settings, you also need the webrtc custom integration, which includes the go2rtc binary, and go2rtc also exists as a standalone add-on. That component converts the peer to peer bytes into an RTSP stream, so you can play it inside Home Assistant, with or without RTC, or with a player such as VLC.

The trade-off is therefore between hardware work and software work. A camera with RTSP hands you a stream directly, and the peer to peer path is the fallback where the camera does the streaming itself.

One caveat the README is honest about: there are modified versions of the Eufy Security Android application floating around which could enable an RTSP stream for devices that do not support it, but the author has not tried them and does not own a peer to peer only device, so they cannot be reproduced locally. That is an explicit statement that this path is untested by the maintainer.

The go2rtc add-on is the second of the four installation steps, after the Eufy Security add-on itself and before the integration.

Your camera will not stream until you call turn_on

The behaviour that makes a first install look broken is described in the installation section, and it is not a fault.

Your camera would not start streaming magically by itself, you have to call the turn_on or turn_off services of the respective camera entities. So when you first install everything, you would not have any video until you call these functions.

The reason is the streaming model. A peer to peer stream is an on demand session, and the integration does not open one until something asks for it. That is also why the README tells you to set the streaming quality to LOW and the streaming codec to LOW in all possible places, otherwise Home Assistant will not be able to handle video generation and or playing.

The LOW requirement is not a suggestion for bandwidth reasons, it is a capability requirement. The stream has to be decodable by the machine running Home Assistant, and a high quality stream produces frames that the pipeline cannot handle.

There is a related instability, described without softening it. Peer to peer streaming might stop randomly because of low level technical issues, and you can restart it again with turn_off followed by turn_on. The README also points out that you can trigger your automation's on camera states, and it names three of them, idle, preparing and streaming, which is what an automation would key on to know when a camera is actually live.

For a first use, then, the sequence is: install the add-on, install go2rtc if the camera needs it, install the integration, add the camera to a dashboard, and then call turn_on and see the stream appear. The dashboard step is the fourth of the four.

Editorial conclusion

Adopt this integration only if you are already running it, or if you are deliberately testing an older arrangement, because the README states the repository will not be updated any further and points to a new implementation, and because the add-on forces other Eufy sessions to log off every time it starts. Do not start a new install on it without reading the successor. Verify first that your devices appear in the known working list of eufy-security-client, that streaming quality and streaming codec are set to LOW as the README insists, and that your camera either speaks RTSP natively or that you are prepared to run the go2rtc add-on to convert the peer to peer stream.

Frequently asked questions

Official sources

1. fuatakgun/eufy_security on GitHub
2. Issues
3. License: MIT
4. README
5. Releases