Skip to main content

Sites

Sites represent physical locations or logical separations in multi-tenant or multi-location GEM installations. Sites enable user access restrictions and location-based organization.

Overview​

The Sites feature allows:

  • Multi-Location Management: Single GEM managing multiple properties
  • Multi-Tenant Isolation: Separate clients in managed services
  • User Restriction: Limit users to specific sites
  • Cross-Site Integration: Link sites for shared resources
GEM Cloud tenants

On a cloud tenant with Account Sync enabled, the site registry maintains itself: the primary renames its own row to its canonical installation name, auto-creates a site row for each tenant peer (named the same way), and pushes those rows to every peer. The tenant's member list in GEM Cloud defines the registry: a site added here by hand that isn't a tenant member stays local to this server. A managed peer's own This Server row is renamed to its canonical name by the sync and is never deleted by it. Rows written this way — on the primary and on the peers — apply themselves and never appear in the pending-changes badge; the tenant binding decided them, so there is nothing to approve. A row created this way gets the tenant's cloud URL (or this server's external_url when there is no tunnel binding), since the updater names no per-site address.

Each tenant row is tied to its server by installation ID, and carries a green Tenant badge. Renaming a server in GEM Cloud renames its row on every site. Its mode link and user memberships stay with it, and so does its label if you edited it. Without an edit, the label follows the new name. A row added before this tracking existed is picked up by its name the first time sync runs.

Viewing Sites​

Sites are displayed as a grid of cards. Each card shows:

  • Label (and internal name if different) - Site display name with an icon: a house for the local server, a cloud for remote sites
  • This Server badge - Highlights the local site with a blue border accent
  • Tenant badge - The row is kept in sync with a GEM Cloud tenant member (hover for its installation ID)
  • Disabled badge - Dimmed if the site is disabled
  • URL - Clickable link for remote sites (opens in a new tab); display-only for the local site
  • Provided by - Shown only when a package installed this site. The package name is a link to it in Applications; editing or deleting a site a package installed changes what an uninstall leaves behind
  • Active Mode badge - The site's currently assigned mode. The badge is a link: click it to open that mode on the Site Modes page, filtered to it
  • Stats Row (local site only) - Live counts of Zones, Devices, Spaces, and Users on this server
  • Action Buttons:
    • View Spaces - On the local site, opens the Site Spaces page on this site's own root space, so the tree is already where you wanted it (a site with no root space recorded opens the bare tree)
    • Edit - Modify the site (not available when this server is managed by another site)
    • Delete - Remove the site (not available when managed)

Toolbar Actions​

  • Add - Create a new site (disabled when this server is managed)

Creating a Site​

To create a new site:

  1. Click Add in the grid toolbar
  2. Configure the site properties (see sections below)
  3. Click Save

Site Configuration​

Site Information​

Name

  • Internal identifier (lowercase_with_underscores)
  • Examples: headquarters, building_a, client_smith, vacation_home
  • Auto-formatted on blur

Label

  • User-friendly display name
  • Examples: "Headquarters", "Building A", "Smith Residence", "Vacation Home"
  • Shown in UI dropdowns and selectors

URL

  • Full URL to remote GEM server (if applicable)
  • Format: https://example.com or https://192.168.1.100:443
  • Include protocol (https:// or http://)
  • Used for cross-site API communication

Settings​

This Server

  • Toggle to mark this as the local site
  • Only one site should have "This Server" enabled
  • Identifies the site on which this GEM server is running
  • Important for:
    • Cross-site routing
    • User site restrictions
    • Remote synchronization

Enabled

  • Toggle to enable/disable the site
  • Disabled sites:
    • Hidden from user selections
    • Cannot be accessed
    • Configuration preserved
    • Useful for seasonal properties or inactive clients

Common Use Cases​

Single-Location Deployment​

For a single home or building:

  1. Create one site (often auto-created):
    • Name: primary
    • Label: "Primary Site"
    • This Server: Yes
    • Enabled: Yes
  2. Leave URL empty (local only)
  3. Do not restrict users to sites

Multi-Location Enterprise​

For a campus or multi-building facility:

  1. Create a site for each building:

    Site 1:
    Name: headquarters
    Label: Headquarters Building
    This Server: Yes
    URL: (empty - local)

    Site 2:
    Name: warehouse_north
    Label: North Warehouse
    This Server: No
    URL: https://warehouse-north.company.local

    Site 3:
    Name: warehouse_south
    Label: South Warehouse
    This Server: No
    URL: https://warehouse-south.company.local

  2. Assign users to appropriate sites:

    • Corporate users: All sites
    • Warehouse managers: Specific warehouse only
    • Security: All sites

Multi-Tenant Service Provider​

For a service provider managing multiple clients:

  1. Create a site for each client:

    Site 1 (This Server):
    Name: provider_hq
    Label: Provider HQ
    This Server: Yes

    Site 2:
    Name: client_smith
    Label: Smith Residence
    This Server: No
    URL: https://smith.gemautomation.net

    Site 3:
    Name: client_jones
    Label: Jones Estate
    This Server: No
    URL: https://jones.gemautomation.net

  2. Create site-specific users:

    • smith_user → assigned to client_smith only
    • jones_user → assigned to client_jones only
    • installer_tech → assigned to all sites
    • admin → assigned to all sites

Vacation Home Network​

For linked primary/vacation homes:

  1. Primary Home (Main GEM):

    Name: primary_residence
    Label: Primary Residence
    This Server: Yes
    URL: https://home.family.net

  2. Vacation Home (Remote GEM):

    Name: lake_house
    Label: Lake House
    This Server: No
    URL: https://lakehouse.family.net

  3. Users:

    • Family members: Both sites
    • House sitter: lake_house only
    • Maintenance: Both sites

User Site Restrictions​

Users can be restricted to specific sites:

No Sites Assigned​

  • User can access all sites
  • Default behavior
  • Appropriate for admins and service providers

Specific Sites Assigned​

  • User can only access those sites
  • Site selector appears in user interface
  • Queries and controls filtered to site
  • Attempts to access other sites are denied

Implementation​

In the Users page:

  1. Edit a user
  2. In the "Sites" section, select one or more sites
  3. Save the user
  4. User will only see and control the selected sites

Cross-Site Communication​

When sites have URLs configured, GEM can communicate across sites:

Supported Features​

Cross-Site Queries:

  • Query zones on remote sites
  • Get attributes from remote devices
  • Monitor status across sites

Cross-Site Commands:

  • Send commands to remote zones
  • Execute macros on other sites
  • Synchronize states

Cross-Site Macros:

  • Macro steps can target zones on different sites
  • "Goodnight" macro can control both home and vacation home
  • Synchronize schedules across properties

Requirements​

  1. Network Connectivity: Sites must be able to reach each other
  2. URL Configuration: Remote sites need valid URLs
  3. Authentication: Cross-site requests use API keys or tokens
  4. Firewall Rules: Allow HTTPS traffic between sites

Example Cross-Site Macro​

// Macro: "Secure All Properties"
Step 1: Lock all doors (primary_residence)
Step 2: Arm security (primary_residence)
Step 3: Lock all doors (lake_house) [via cross-site API]
Step 4: Arm security (lake_house) [via cross-site API]
Step 5: Send notification: "All properties secured"

Site Selection UI​

When a user has site restrictions:

  1. Site Selector: Dropdown appears in navigation
  2. Filtered Views: Only shows zones/devices from selected site
  3. Switching Sites: User can change between assigned sites
  4. Default Site: First assigned site selected by default

Security Considerations​

Site Isolation​

Benefits:

  • Prevents users from accessing wrong properties
  • Maintains client privacy in multi-tenant
  • Reduces accidental control of wrong location

Implementation:

  • Assign users to specific sites
  • Ensure roles don't override site restrictions
  • Audit site assignments regularly

Cross-Site Security​

Risks:

  • Cross-site requests expose data between locations
  • Compromised site could access other sites
  • Network traffic contains sensitive control data

Mitigations:

  1. Encryption: Always use HTTPS URLs
  2. Authentication: Use strong API keys
  3. Firewall: Restrict cross-site traffic to known IPs
  4. VPN: Consider VPN for cross-site links
  5. Monitoring: Log all cross-site API calls

URL Security​

Public URLs:

  • Use valid SSL certificates
  • Implement rate limiting
  • Enable 2FA for remote users
  • Monitor for suspicious activity

Private URLs:

  • Use VPN or private network
  • Consider IP whitelisting
  • Use self-signed certs if needed
  • Isolate from internet

Troubleshooting​

User Cannot See Site​

Check:

  1. Site Enabled: Verify site is enabled
  2. User Assignment: Check user has site assigned (or no sites = all access)
  3. This Server: Ensure local site has "This Server" set correctly
  4. Login Again: User must re-login after site assignment changes

Cross-Site Commands Failing​

Check:

  1. URL: Verify remote site URL is correct and accessible
  2. Network: Ping or curl the remote URL
  3. Authentication: Verify API credentials are valid
  4. Firewall: Check firewall rules allow HTTPS between sites
  5. Logs: Review logs on both sites for error messages

"This Server" Set Wrong​

Symptoms:

  • Site selector shows wrong site as current
  • Cross-site routing fails
  • User restrictions not working

Solution:

  1. Identify the correct local site
  2. Edit that site, set "This Server": Yes
  3. Edit other sites, set "This Server": No
  4. Restart GEM for change to take effect

Site Selector Not Appearing​

Cause:

  • User has no site restrictions (can access all)

Expected Behavior:

  • Site selector only appears when user is restricted to 2+ sites
  • If user assigned to 1 site, that site is always active (no selector)
  • If user assigned to 0 sites (empty), all sites accessible (no selector)

Best Practices​

  1. Clear Naming: Use descriptive site names and labels
  2. Documentation: Document which site corresponds to which physical location
  3. Consistent URLs: Use DNS names instead of IP addresses when possible
  4. Test Connectivity: Verify cross-site communication works
  5. User Training: Educate users about site selector if applicable
  6. Regular Audits: Review site assignments quarterly
  7. Disable Unused: Disable seasonal or inactive sites instead of deleting

Advanced Topics​

Programmatic Site Management​

Sites can be managed via API:

// Create site
await GemApp.getInstance().insertModel('site', {
    name: 'new_location',
    label: 'New Location',
    url: 'https://new-location.example.com',
    is_me: false,
    enabled: true
});

// Query sites
let sites = await GemApp.getInstance().query('site', {enabled: true});

// Update site
await GemApp.getInstance().updateModel('site', siteId, {
    url: 'https://updated-url.example.com'
});

Site Synchronization​

For synchronized multi-site deployments:

  1. Shared Configuration: Export/import configs between sites
  2. Macro Sync: Keep macro libraries identical
  3. User Sync: Maintain consistent user accounts
  4. Schedule Sync: Coordinate time-based events

Consider developing custom sync scripts for large deployments.

Site Failover​

For high-availability:

  1. Configure backup URL in site
  2. Implement retry logic in cross-site calls
  3. Monitor site availability
  4. Alert on site communication failures