Homes and the Homer server
Where the home lives
A home is the plan, the devices on it, groups, items and display settings. It's stored on the Homer server — a service next to Home Assistant. Apps and browsers take the home from there and write edits back there.
- Edits spread by themselves. You fix the plan on the tablet — the phone, TV and browser get the new home right away, without exporting and importing a file.
- The server checks the edit base. If two people save the home at the same time, the second one sees a conflict and a choice, instead of silently overwriting someone else's work. The app does the same: if the home was edited in two places — on this device and somewhere else — it asks The home was edited in two places: Take server version (all edits made here are lost) or Keep mine (it stays only on this device, and you'll be asked again at the next sync). It never silently sends an old copy over the server one.
- No Home Assistant account is needed for editing. A device signed in through the Homer server edits the home according to its access level.
Besides the home, the Homer server stores models and textures (asset storage), access, the log, the chat and alarms.
Several homes
One Homer server and one Home Assistant can hold several homes: a flat, a country house, a sauna. Each has its own plan, while Home Assistant devices are shared. In pickers, entities of other homes go under a separate “In other homes” button so they don't get mixed up with your own.
The list of Homer server homes is kept on the server. At least one home is created on first run. A new home is added to the Homer server by whoever installed the stack: there is no “create a home on the server” button in the app.
Access opens selected homes: you can give a guest the country house and not the flat. See Access and levels.
Homes in the app
Settings → Home → Homes. The list of homes on this device. Each has its own plan and its own connection; switching changes both.
| Button | What it does |
|---|---|
| Choosing in the list | Opens the home. Right away, no “apply” |
| Name | Rename. For the open home, the name goes to all its devices |
| Remove | Removes the home from this device. Nothing changes on the Homer server or in Home Assistant |
| Add home | A new home with a demo plan, the connection is entered next |
| Home from file | A new home from a .json or .homer file |
If your access opens several homes on one Homer server, a “Plans of this server” block appears below. Open adds the home to the list with the same Homer server address and secret: no need to get acquainted again.
In the web version, homes are switched with a drop-down in the header.
Homer server
Settings → Access → Homer server.
| Field | What to enter |
|---|---|
| Home address | The home server address on the home network, port 8730. Empty — the app takes the Home Assistant address with port 8730 |
| External address | The address through a reverse proxy, for those who aren't at home. Empty — the home isn't reachable from outside for anyone |
Check asks the Homer server whether it answers and who you are to it. If the Homer server knows its own addresses, it fills them into empty fields — check them and tap Save.
Further down on the same card is signing in to the home: Become owner or Accept invite. If you're already signed in — invites, access and the log. More — Access and levels.
Home Assistant address and token
Settings → Home → HA address and token. The owner needs them once, to become the owner. Other devices signed in through the Homer server don't need these fields: plan, lights and walk go through the Homer server. A guest never gets a Home Assistant account at all.
Home location
Settings → Home → Home location → On the map. In the web version: Edit → Home: name, tariff, step, location…
The coordinates give the sun's height, and the home's rotation gives which windows it shines into. Until a point is set, the Home Assistant server coordinates are used.
- Tap the map to put the home at a point.
- Drag the ↻ handle to turn the home outline along the streets and neighboring houses on the map.
- I'm here — a point from the device's location.
- North up resets the rotation.
- Forget point goes back to the Home Assistant coordinates.
- The latitude, longitude field → Go moves the point by numbers, for example
55.75, 37.62.
Base map: MapTiler key
The map under the outline is MapTiler tiles, loaded with the home's key. Without a key there is no base map: the outline, the crosshair, I'm here and entering coordinates still work, and the bottom of the map tells where to get a key.
- Sign up at cloud.maptiler.com — the free plan is enough for a personal home.
- Copy the key from Account → API keys.
- In Home location tap Enter key (or Map key if a key is already set), paste it and tap Save.
The key is kept on the Homer server, one per home, and works on all devices at once. Only the owner enters it: MapTiler requests go on the owner's plan. The key never goes into the states socket, the home config or its export.
The browser and the app fetch MapTiler tiles from MapTiler directly, from api.maptiler.com: the MapTiler Cloud terms forbid fetching them through your own server (a proxy) and storing them there without a separate agreement. Tiles may be kept only in the cache of the device itself, and that is what Homer does. So the server gives the MapTiler key to those who edit the home, and it is worth restricting in the MapTiler account (Account → API keys → the key → Allowed HTTP origins): enter the address of the home's web version. The Android app sends requests without an Origin, so if you need the map there too, add ? (“unknown origin”) to the list — or create a separate key for the app. A safety net against strangers' requests is the spending limit in the MapTiler account: on the free plan the key simply stops working until next month once the limit is reached.
Another provider — a template for 256 px tiles with {z}, {x}, {y} and {key} in place of the key, plus the provider attribution. An empty template goes back to MapTiler Streets. Tiles of your own provider go through the Homer server: it puts the key into the template, fetches the tile and hands it to the app and the browser, so neither the key nor the template reaches them — only the owner sees them in the Map key window (the key as dots; it can only be replaced). The server keeps tiles on its disk — no more than 200 MB for all homes and no longer than the provider's headers allow (30 days without them); changing the key or the template clears the home's cache. Limits:
- the address must be
https, with no login or password in it; - local network addresses are not accepted (
localhost,192.168.…,10.…,.local, names without a dot and so on), and the server will not open a name that DNS resolves to such an address either: otherwise the Homer server could be used to look into the home network; - no more than 20 tiles per second per access (with a burst of 240 at the start);
tile.openstreetmap.orgtiles are not accepted: the OpenStreetMap rules forbid them for apps that are sold;- a template on
*.maptiler.comis MapTiler: its tiles go directly, as above.
If the provider does not accept the key (a 401 or 403 answer), the map shows: The map key was not accepted — check it in “Home location”, and the owner gets a Map key button.
With MapTiler the map corners show its logo (a link to maptiler.com, required on the free plan) and the attribution “© MapTiler” and “© OpenStreetMap contributors” linking to their copyright pages — the MapTiler attribution rules require it. Your own provider gets only a text attribution (or its address if no attribution is set).
Copying and moving a home
In the app: Settings → Files → Home configuration. In the web version: Settings → Files → Home as a file.
| Button | What you get |
|---|---|
| Export | One JSON: plan, devices, groups and light presets |
| With items | A .homer archive: the same plan plus textures and models. Comes up on a clean device without internet |
| Import | Replaces the plan of the open home completely. Presets from the file are written to Home Assistant |
| Copy from asset storage | A .homer archive built by the Homer server: it also has items sent by a guest editor, and the Homer and Home Assistant settings. Owner only |
The Whole home checkbox (owner only) adds Homer and Home Assistant settings to the same .json or .homer file — see Whole home.
The app and the web version read each other's files.
A file from the app is a key to the home
An export from the app includes the Home Assistant address and token: that way the home comes up on another device in one step. Don't send such a file in a messenger and don't put it in a shared folder. A file from the browser has no address or token.
Before a big edit
Save a Copy from asset storage. It's a full copy of the home with all files, and importing it brings everything back.
Whole home
Plan, presets and items aren't the whole home: after moving to a new server or reinstalling Home Assistant, areas, names and automations had to be set up again by hand. The Whole home checkbox at export (app and web version) puts settings into the file too:
| From | What goes into the file |
|---|---|
| Homer | Speaker wake words and voices, the sky, the sleep schedule and other home settings — from an allow-list only |
| Home Assistant | Labels, floors and areas, helpers, names, areas and aliases of devices and entities, automations, scripts and scenes made in the UI, homer_*.yaml packages |
What never goes into the file:
- Tokens and keys — Telegram, Music Assistant, Yandex, the Home Assistant account, the speaker PIN, provider and map keys, this machine's addresses. A key planted into the file by hand is rejected on import: a file from a friend must not be a way to slip a foreign token to the server.
- Integrations — Zigbee, Yandex and others: they have keys and hardware. The file only lists them, and import names the missing ones — install them in Home Assistant, preferably before importing.
- YAML automations — export tells how many were left out.
Import first shows a report: what will be created, what will change, what won't fit and why. It writes only after you say yes. Internal ids differ on a new Home Assistant, so devices are matched by hardware — the Zigbee address (ieee) and MAC. An entity that got a new entity_id after a reinstall gets its old one back: the plan, automations and scenes from the same file refer to it.
Only the owner sees the checkbox, and only the owner moves settings from a file: for others, import replaces the plan and leaves the settings block untouched. Older app builds simply ignore the block.
Home versions on the server
The Homer server keeps the home by itself, no buttons needed: every accepted edit, then one copy per day for a month and one per week for half a year. You can restore any of them — the current home goes into the versions too, so a restore can be undone the same way.
In the app: Settings → Files → Home versions. In the web version: Settings → Files → Home versions. Only the owner can restore.
Edit rollback
You can apply a plan edit with a safety net.
- In the web version, editing has three ways to save: Apply now, Apply now, roll back in 10 min and, if you're not the owner, Save as a draft.
- With rollback, everyone sees a bar with a timer above the plan. The owner taps Keep — the edit stays. If nobody taps it within 10 minutes, the home goes back by itself. Roll back now rolls back at once.
- A draft doesn't change the home. The owner sees a bar, looks at the plan with the changes highlighted and taps Accept, Accept for trial (10 min) or Reject. Discuss posts a question about the edit to the home chat.
The Homer server also keeps the last ten accepted versions of the home. This is insurance in case of a conflict; there is no button in the app to go back to them.