Community Setup

Community Edition runs Homecast entirely on your Mac with no cloud dependency. Control your Apple Home devices from any browser, REST API, or AI assistant on your local network.

What's included

Community Edition gives you the same device control experience as Homecast Cloud, running locally:

• Web dashboard at http://your-mac.local:5656
• REST API for scripts and automation
• MCP endpoint for AI assistants (Claude, ChatGPT, etc.)
• Real-time updates via WebSocket
• Automations — view and manage HomeKit automations
• Collections — organize devices into custom groups
• Sharing — share access via links with optional passcode
• Local authentication — optional, with user roles

No account needed. No data leaves your network.

Setup

Step 1: Install the app

Download Homecast from the Mac App Store.

Build from source

See the GitHub repo for build instructions if you prefer to compile it yourself.

Step 2: Select Community mode

On first launch, choose Community from the mode selector. The app starts a local server on port 5656.

Step 3: Grant HomeKit access

macOS will prompt for HomeKit permission. Accept it — this is how Homecast reads your devices.

Step 4: Open the dashboard

On the same Mac, the dashboard loads automatically.

On the iOS or Android app, choose Community and your Mac appears in a list — the app finds it on the network for you. Pick it and you're connected. Nothing to type.

In a browser on another device, open:

http://your-mac.local:5656

Replace your-mac with your Mac's hostname, or use its IP address directly (e.g., http://192.168.1.100:5656).

Find your Mac's address

Run hostname in Terminal to see your Mac's hostname, or check System Settings > General > Sharing for the local hostname.

Nothing found?

Some networks don't carry the discovery traffic Homecast uses — guest Wi-Fi, networks with client isolation switched on, and a few mesh systems all block it. Type the address instead; the field is always there below the list.

On iPhone and iPad, also check that Homecast has Local Network permission in Settings → Privacy & Security → Local Network. Discovery needs it.

Authentication

Authentication is off by default — anyone on your local network can access the dashboard and API. To restrict access, enable authentication in Settings.

How it works

• First user to sign up becomes the owner
• Owner can create additional users with roles
• Credentials are username + password (no email required)
• Tokens expire after 30 days

Roles

Role	Dashboard	Control devices	Manage users	Manage settings
Owner	Yes	Yes	Yes	Yes
Admin	Yes	Yes	Yes	No
Control	Yes	Yes	No	No
View	Yes	No	No	No

API tokens

For scripts and automation, create API tokens in Settings > Access Tokens. These use the hc_ prefix and work with both the REST API and MCP endpoint.

# Use an API token
curl http://your-mac.local:5656/rest/homes \
  -H "Authorization: Bearer hc_your_token_here"

If authentication is disabled, requests work without any token.

REST API

The local REST API mirrors the cloud REST API, served at http://your-mac.local:5656/rest/.

Endpoints

Method	Endpoint	Description
GET	/rest/state	Simplified device state (filter: ?home=X&room=X&type=X&name=X)
POST	/rest/state	Control devices (nested dict format)
GET	/rest/homes	List all homes
GET	/rest/accessories	List accessories (filter: ?home=X&room=X&type=X&name=X)
GET	/rest/accessories/:id	Get a single accessory
GET	/rest/scenes?home=X	List scenes
POST	/rest/scenes/:id/execute	Execute a scene by UUID
POST	/rest/scene	Execute a scene by name
GET	/rest/rooms?home=X	List rooms

These are the same endpoints as the cloud REST API.

Examples

# Get simplified state (AI-friendly format)
curl http://your-mac.local:5656/rest/state

# Get state filtered by room
curl "http://your-mac.local:5656/rest/state?room=bedroom"

# Turn on a light (use slug keys from /rest/state response)
curl -X POST http://your-mac.local:5656/rest/state \
  -H "Content-Type: application/json" \
  -d '{"my_home_a1b2": {"bedroom_c3d4": {"bedside_lamp_e5f6": {"on": true}}}}'

# Execute a scene by name
curl -X POST http://your-mac.local:5656/rest/scene \
  -H "Content-Type: application/json" \
  -d '{"home": "my_home_a1b2", "name": "Good Night"}'

# List all homes
curl http://your-mac.local:5656/rest/homes

MCP for AI assistants

Point any MCP client at http://your-mac.local:5656/mcp to give AI assistants control of your home.

Available tools

Tool	Description
get_state	Get state across all homes (filterable by home, room, type, name)
set_state	Control devices with a list of updates (on, brightness, color, etc.)
run_scene	Execute a scene by home and name

Claude Desktop / Claude Code config

Add to your MCP settings:

{
  "mcpServers": {
    "homecast": {
      "url": "http://your-mac.local:5656/mcp"
    }
  }
}

If authentication is enabled, add a header:

{
  "mcpServers": {
    "homecast": {
      "url": "http://your-mac.local:5656/mcp",
      "headers": {
        "Authorization": "Bearer hc_your_token_here"
      }
    }
  }
}

WebSocket

Real-time device state updates are available via WebSocket on port 5657:

ws://your-mac.local:5657

Messages use JSON format:

{"id": "uuid", "type": "request", "action": "homes.list", "payload": {}}

Remote access

Discovery only works on the network you're actually on. From anywhere else, type the address instead — every client takes a full URL, including https://, so whichever route you pick below, you enter it in the same place: the app's address field, or Settings → Server URL in a browser.

Tailscale, or any mesh VPN (recommended)

No open ports, no public hostname, nothing exposed to the internet.

1. Install Tailscale on your Mac and on the phone
2. Sign in on both with the same account
3. On the Mac: tailscale ip -4 → e.g. 100.92.14.3
4. In the app, enter http://100.92.14.3:5656

Both of Homecast's ports are reachable over the mesh, so nothing else is needed.

Cloudflare Tunnel

Also no open ports, but it does create a public hostname — so turn on authentication first, and consider putting Cloudflare Access in front of it.

The one thing to get right: Homecast serves its WebSocket on its own port, HTTP + 1. A tunnel that forwards a single port will load the dashboard and then never update it. Route /ws separately in ~/.cloudflared/config.yml:

ingress:
  - hostname: homecast.yourdomain.com
    path: ^/ws
    service: http://localhost:5657
  - hostname: homecast.yourdomain.com
    service: http://localhost:5656
  - service: http_status:404

Then enter https://homecast.yourdomain.com in the app. Reached on a bare https:// host with no port, Homecast looks for the WebSocket at /ws on that same origin — which is what the rule above serves. nginx and Caddy need the same split.

Port forwarding

Forward 5656 and 5657 — the second carries the WebSocket. This puts your Mac directly on the internet; prefer Tailscale.

Turn on authentication first

Authentication is off by default. On your own network that is merely relaxed; on a public hostname it means anyone who finds the address controls your home. The apps will stop and warn you before connecting to an unprotected relay at a public address, but the fix belongs on the relay — see Authentication above.

Or use Homecast Cloud for built-in remote access without any tunnel setup.

Community vs Cloud

Feature	Community (free)	Cloud
Device control	Yes	Yes
REST API	Local network	Anywhere
MCP for AI	Local network	Anywhere
Dashboard	Local network	Anywhere
Automations	Yes	Yes
Collections	Yes	Yes
Sharing	Local links	Cloud links with passcode/expiry
Home Assistant	Yes (via integration)	Yes (via integration)
MQTT	Local broker	Local or cloud broker
Push notifications	Local (macOS only)	Push, email, local + preferences
Webhooks	No	Yes
Smart Deals	No	Yes
Remote access	Via tunnel	Built-in
Account required	No	Yes
Price	Free	See pricing

Usage statistics

Community Edition sends one anonymous report every 24 hours so we can see how many relays are running, how large the homes they serve are, and which app versions are still in the field. It contains counts only — never the names of your homes, rooms or accessories, never any accessory state, and never your IP address.

The full field list is published at What Community Edition Sends. If the report cannot be sent, nothing happens and the relay carries on as normal.