Community Edition

Run 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. From other devices on your network, 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.

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

Community Edition runs on your local network. For access outside your home, use a tunnel:

• Tailscale (recommended) — zero-config VPN with valid HTTPS certs
• Cloudflare Tunnel — free, requires a Cloudflare account
• Port forwarding — forward port 5656 on your router

WARNING

If exposing your server to the internet, enable authentication first to prevent unauthorized access.

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