Homes: more than one, where each runs, and how it links

A person can hold grants for more than one home. The platform returns them in homes[] from GET /auth/me, and the console lets the user switch between them in the top bar when there is more than one. The phone shows the same choice in the Home panel, the widget follows that selection, and when the phone has not chosen a home yet the nearest home by coarse location becomes the default. A manual choice stays in effect until the user picks Use nearby home again. The platform does not store the user’s location for this; it uses the home’s coordinates from its address.

What a home list contains

homes[] includes every home a person can access, open or not. Each entry carries the tenant, the client, the home name, the home coordinates, the person’s role, a guest’s until when there is one, the status and its sentence, and from this phase hosting and link. For a household, the Connection page shows each home with its hosting sentence and its link. For staff, the page is Homes and links and shows every property of the tenant with the same information.

The selection is remembered per browser. Every page reads the selected home from useHousehold.

Creating another home

+ New home lives on the Connection screen for the Owner. Creating a home starts with a name and an address. The address is geocoded at creation, so the weather, the sun, and the nearest-home rule work from the first minute. After that come the first rooms, then the hub provisioning flow. Rooms belong to the home, and connectors belong to the client.

Hosting and where software runs

Property.hosting decides where a home’s software runs.

hosting	Who	What runs where
PLATFORM	a household with a hub	nothing in the house but the hub, which links outbound to the platform; each cloud connector is one shared process per kind for every home; local kinds go through the home’s own hub
SELF	the DIY enthusiast, or an installer with a box	the agent container on the box, its own voice stack if wanted, and local connectors on the box

PLATFORM is the default for a new household home. Only staff may set hosting. A household’s new home starts as PLATFORM. A SELF home keeps running on the box.

For developers, this matters because the route is chosen from the home’s hosting, not from the connector alone. A local kind on a PLATFORM home is driven by the home’s hub. Cloud kinds stay cloud kinds. A cloud connector does not work if its cloud path is unavailable.

The link

A home’s link describes the liveness of the thing that holds its outbound connection: the hub for a PLATFORM home, or the agent for a SELF home. The value is derived from lastSeen and is never stored as a separate fact. homes[].link is either null or an object with state, lastHeardAt, and deviceName.

The Connection page uses these sentences:

• Hosted by ALYT. The hub links when it is provisioned; nothing runs in the house but the hub.
• Linked, last heard 12 s ago.
• Not linked yet.

A PLATFORM home with no hub yet shows the first sentence. A hub or agent that is online shows the second. A registered hub that has never been heard shows the third.

TV homes and switching

Apple TV and Google TV also show the switcher in the header. A television does not receive an account-wide home list or a phone refresh credential. Each property is approved separately, and the receiver labels the local list Homes approved on this TV. Switching replaces the complete bearer, property, and storage scope before the next dashboard loads. Security sharing, assigned room, and revocation remain independent per property.

Relevant access boundaries

Household permissions are narrower than staff permissions. DEV credentials act in the developer sandbox. LIVE credentials only act for the installed connector they belong to.

Those boundaries matter when you read or switch homes, because the selected home only controls what the current session can access within its own grant and scope.

Phone account sessions

For ordinary phone sessions and opt-in ordinary household auth, the phone keeps account-scoped cached home and avatar reads, while saved reads carry freshness information and avatar photos do not. Another sign-in shows that account’s own home list and avatar, and an account with no home stays empty; signing out removes the cached home and profile, and password reset, logout, replay revocation, or credential expiry still end access and require signing in again. After an update, the app must verify the owning account online once for legacy credentials; if that check cannot finish, keep connecting, retry on foreground, and preserve the credential without showing another account’s saved home. For ordinary household POST /auth/refresh, accept an optional rotationKey of 32 cryptographic random bytes encoded as 64 lowercase hex characters, persist it atomically with the original refresh token before transmission, treat the token and attempt together as credentials, never put them in logs or widget storage, and never extend expiry: an identical uncertain-attempt retry recovers the same immediate live successor until it rotates or is revoked or expired, while a different attempt or older ancestor cannot recover it. No changes apply to ESP, MCP, Environment Graph, model or AI projection, partner technician, developer, Alexa, TV, credential-bound, or authority flows.