The Complete Reef Trak Home Assistant Bridge Guide

The short version

The Reef Trak bridge is an integration that runs inside your Home Assistant. You choose the devices that belong to one tank, and the bridge sends their readings to that tank in Reef Trak. Smart plugs, heaters, temperature probes, leak sensors, lights, pumps, and fans can appear in the Reef Trak app while you are at home or away.

Live changes normally arrive in about two seconds. Numeric readings build an hourly history for seven days, so a temperature or power card becomes a trend instead of a moment. The integration download is free. Pairing it to a tank is a Reef Trak Premium feature because the live relay, history, and remote app view use ongoing cloud infrastructure.

The most important fact comes first: this bridge is monitoring only. It cannot switch, dim, cycle, or command equipment. That is not a button we hid for the beta. The control path does not exist.

What Home Assistant is, and who this is for

Home Assistant is an open-source home automation platform that runs on hardware you control. It brings equipment from many brands into one local system. In a reef room, that might mean a Kasa power-monitoring plug under a heater, an Inkbird temperature sensor, a return pump, a fan, and a floor leak sensor all reporting through one interface.

It can run on Home Assistant Green or Yellow, a Raspberry Pi, an old PC, a virtual machine, or a container on a NAS or unRAID server. Home Assistant Operating System is the easiest path for most new users. Container and virtual-machine installs are good fits for people who already run servers at home.

Home Assistant is powerful because it is a real system, not a disposable gadget app. That also means it has a learning curve. You own a small always-on server, its updates, and its device setup. If that sounds interesting, this bridge is built for you. If it sounds like another job, Reef Trak still works without Home Assistant and nothing in the normal tank workflow depends on it.

What the bridge does and what it never does

The integration listens for state changes from the tank devices you selected. It batches those changes and sends them to Reef Trak over an outbound HTTPS connection. A heartbeat reports that the bridge is healthy, and a periodic full snapshot corrects any drift after a restart or temporary outage.

The bridge contains no service calls for turning devices on or off. Its server protocol has no control message, and its credentials have no control permission. A modified app would still have nothing to send. If you want to switch equipment, you use Home Assistant itself or the equipment manufacturer’s app.

That boundary matters around heaters, return pumps, dosing systems, and other life-support equipment. A remote command that is delayed, repeated, or sent to the wrong device can harm livestock or create a fire or flood risk. Reef Trak watches and reports. It does not act on the tank.

Exactly what leaves your house

Privacy is enforced by the design of the integration. During setup, Home Assistant shows you the available devices and you select the ones that belong to the tank. Only those selected devices are uploaded. Reef Trak never receives the complete Home Assistant device list.

For a selected device, the bridge sends its display name, state or numeric value, unit, availability, timestamps, and a small allowlist of details needed to make the card useful. Examples include brightness, fan speed percentage or RPM, heater action, current temperature, and target temperature. Unknown fields are removed instead of being passed through.

The bridge sends the minimum information needed for tank monitoring.

Everything travels from Home Assistant to Reef Trak over HTTPS. The integration does not open a listening port, create a tunnel, or expose the Home Assistant server to the internet. Pairing uses a Reef Trak code, not the Home Assistant login.

Before you install

• Home Assistant 2025.6 or newer, running on any supported platform
• The Reef Trak app on iPhone or Android, signed in to your account
• Reef Trak Premium on the account that owns the tank
• At least one tank device already working in Home Assistant
• Terminal access for the one-command installer, or file access for the manual zip method

On Home Assistant Operating System, install Terminal & SSH from Settings > Apps. Older Home Assistant screens may call this area Add-ons. If you run Home Assistant Container, use the shell or file access you already use to manage its configuration directory.

You do not need special aquarium hardware. Start with equipment that is already useful in Home Assistant. A power-monitoring plug under a heater can reveal whether the heater is actually drawing power. A temperature probe adds an independent reading. A leak sensor beside the sump watches a failure mode that aquarium controllers often miss.

Install the integration step by step

The installer places the Reef Trak integration in Home Assistant’s configuration directory. It does not pair an account or select devices. Those choices happen after the restart.

1. Open Terminal & SSH. In Home Assistant Operating System, go to Settings > Apps, or Settings > Add-ons on older screens. Install Terminal & SSH, start it, and open its web interface. Existing SSH access works too.
2. Run the installer.

   curl -sSL https://reeftrak.com/homeassistant/install | sh

   The script finds the Home Assistant configuration folder and installs custom_components/reeftrak.
3. Restart Home Assistant. Go to Settings > System > Restart. A reload is not enough after installing a new custom integration.
4. Create a pairing code in Reef Trak. Open the tank, tap the house icon in the header, and choose Pair through Reef Trak cloud. Reef Trak displays a six-character code. It expires after 10 minutes, and you can make another code at any time.
5. Add Reef Trak in Home Assistant. Go to Settings > Devices & Services > Add Integration, search for Reef Trak, and enter the code.
6. Select only tank equipment. The picker is the privacy boundary. Check the devices that belong to this tank. Leave every unrelated device unchecked.
7. Return to the Reef Trak tank. The bridge status and selected devices should appear within seconds. History cards begin empty and fill as real readings arrive.

Pairing, credentials, and revocation

The six-character code is a short-lived invitation for one tank. Home Assistant exchanges it at reeftrak.com for credentials that belong only to that bridge installation and tank. Your Home Assistant login is never part of the exchange.

The bridge uses short-lived tokens and rotates them automatically. The server stores cryptographic fingerprints instead of reusable token text. Reusing a stale token revokes the installation, which limits the usefulness of copied credentials.

You can disconnect from either side. Removing the integration in Home Assistant stops the source. In Reef Trak, open the Home Assistant module menu, choose Connected bridges, and revoke the installation. Revocation cuts the data flow immediately. You can pair again later without penalty.

Choosing devices without building a junk drawer

Home Assistant installations can contain hundreds of entities. Many are diagnostic, duplicated, unavailable, or unrelated to the aquarium. Do not select everything. The everyday Reef Trak dashboard is meant to answer what the tank is doing, not reproduce the Home Assistant administration screen.

Start with two or three devices that change a decision: temperature, heater power, return-pump state, or a floor leak sensor. Add lights, fans, and other equipment after the first set is readable. Device names are for people, not permanent identifiers, so choose the actual device in Home Assistant instead of relying on a familiar name alone.

• Temperature probe: confirms water temperature and builds a real trend
• Power-monitoring heater plug: shows whether the heater is drawing power
• Return-pump or circulation-pump state: makes an unexpected stop visible
• Leak sensor: stays quiet when dry and becomes prominent when wet
• Light, fan, or climate device: read-only state and useful operating details

You can change the selected devices later from the integration’s Configure action in Home Assistant. Newly checked devices begin sending after the updated selection is saved. Unchecked devices stop being included.

What you see in Reef Trak

Inside the tank’s Home Assistant module, a status card summarizes bridge health, the number of devices, the latest connection time, and any warnings. Equipment cards are grouped into useful categories instead of one enormous raw entity grid.

Animated icons move only when the underlying device state says the equipment is running. A temperature or power card can show a mini trend from real history. A leak sensor stays calm and readable when it reports Dry, then becomes an alert when it reports moisture.

Tap a meaningful numeric device for a larger reading, a 24-hour or 7-day chart, and low, high, and average values. Power devices can also show energy used today, energy used this week, and peak draw when those readings exist. The app does not manufacture missing values to make a card look complete.

How live data and history stay honest

State changes are batched and normally reach Reef Trak within about 1.5 to 2 seconds. A heartbeat arrives every minute, and the bridge sends a complete snapshot every 15 minutes. The snapshot allows the cloud view to converge on Home Assistant again after a restart, missed event, or temporary network problem.

Numeric readings are folded into hourly minimum, maximum, and average buckets. The beta keeps seven days of these buckets. A new chart begins with Collecting history because there is no past data to draw. The line grows only from readings the bridge actually received.

If Reef Trak has not heard from the bridge for more than five minutes, every affected reading changes to Last known and the app shows an amber Bridge offline for N min message. Old data never pretends to be live data. When Home Assistant returns, the bridge normally recovers on its own within about 90 seconds.

Beta limits you should know

• This is a real beta. Screens will improve, and data flow may pause while problems are fixed.
• Supported Home Assistant domains are sensors, binary sensors, switches in read-only mode, lights in read-only mode, fans, and climate devices.
• Cameras are deliberately excluded. The bridge does not send camera images.
• History is limited to seven days during the beta.
• The bridge does not write readings into Reef Trak’s normal parameter log yet.
• The bridge does not calculate a complete tank electricity cost yet.
• The bridge does not control equipment, run automations, or replace Home Assistant alerts.

Beta means you should expect rough edges in the monitoring experience. It does not mean the bridge has temporary authority over your equipment. Monitoring only is the architecture today, not a beta preference.

Updating and troubleshooting

During the beta, update by running the same install command again and restarting Home Assistant. The installer replaces the integration files. Your pairing and device selection survive the update.

Fast checks for the most common setup problems.

For beta help, email support@reeftrak.com. Include the Home Assistant version, Reef Trak integration version, affected device type, what the Home Assistant entity currently shows, and what the Reef Trak card shows. Do not send passwords, access tokens, pairing codes, camera images, or a full Home Assistant configuration export.

Starting from zero with Home Assistant

If you do not have Home Assistant yet, treat it as a small home-server project. Home Assistant Green is the simplest hardware path because the operating system is installed and the box only needs power and a network connection. A Raspberry Pi 4 or 5 with Home Assistant Operating System is the common do-it-yourself path. An existing NAS, unRAID server, old PC, or virtual-machine host can also work if you are already comfortable maintaining it.

Begin with a few aquarium devices, not twenty. A temperature sensor, a power-monitoring heater plug, and a leak sensor form a useful first set. Get them stable and clearly named in Home Assistant. Then install the Reef Trak bridge. The bridge setup takes minutes once Home Assistant and the equipment are already working.

Home Assistant remains the place where devices are discovered, configured, controlled, and automated. Reef Trak adds a tank-focused monitoring view beside the logs, livestock, maintenance, dosing, and other context you already keep for the aquarium.

What is planned next

The next direction is to let selected readings, such as temperature, flow into Reef Trak’s normal parameter history on a sensible cadence. Energy analytics are also planned so a reef keeper can understand what the tank costs to run and how equipment draw changes over time.

Reading Apex and HYDROS data through their Home Assistant integrations is being explored. That could bring controller tanks and commodity smart devices into one tank view without giving Reef Trak the controller vendor’s cloud login.

Those are plans, not promises or current beta features. Equipment control is not on the near-term path. Any future control design would require independent power feedback, explicit safety thresholds, no automatic retry, high-risk exclusions, and a kill switch. Today’s promise remains simpler: Reef Trak watches.

The bottom line

The Reef Trak Home Assistant bridge is for reef keepers who already use flexible smart-home hardware and want its tank readings beside the rest of the aquarium record. It turns a mixed set of temperature probes, smart plugs, pumps, fans, lights, and leak sensors into one focused monitoring surface that is available away from home.

Its boundaries are as important as its features. You choose the devices. Only their allowed readings leave the home. Stale data labels itself. Empty history stays empty. Credentials can be revoked. No command can return to the equipment because the bridge contains no control path.

Install the integration, pair one tank, select a small group of useful devices, and let real history build. That is the beta: practical monitoring, honest limitations, and no claim that old data or missing control is something else.