Setup & API Docs — Installation, Firmware & Configuration

Onboarding

Hardware onboarding, step by step

Connect the gateway to your LAN

Plug the Gateway Pro into a free Ethernet port on your router (or a PoE switch — PoE 802.3af is fully supported). The device boots in under 20 seconds and announces itself via mDNS as aetherhome-gw.local. Wi-Fi-only setup is supported on Gateway Lite via a WPS-style captive portal.

Open the local console

Navigate to https://aetherhome-gw.local from any device on the same network. Accept the self-signed certificate (it is pinned to your unit's serial number) and set a local admin password — minimum 12 characters.

Claim the gateway to your cloud account

In the console, open Cloud → Claim and scan the pairing QR code from your AetherHome account page. The gateway generates an X.25519 key pair, keeps the private key in its TPM and sends only the public part to the cloud. Claiming is revocable at any time.

Pair your first devices

Put your Zigbee or Thread device into pairing mode and press Devices → Add in the console. Discovery runs for 60 seconds per protocol. Devices appear with friendly names you can edit; each is assigned a stable topic like aetherhome//rooms/living/sensor.humidity.

Verify telemetry is flowing

Open Telemetry in the console — you should see live readings within seconds. The status LED on the gateway switches from breathing blue (cloud sync active) to solid green (all channels healthy).

Advanced

Firmware flashing (optional)

Gateways ship with signed production firmware. You only need this section for early-access builds or recovery after an interrupted update.

1. Download the signed image

Fetch the image bundle from https://dl.cloud-core.casa/firmware/ and verify its signature:

verify signaturebash

# verify against our public release key
aether-verify \
  --image ah-gw-pro-2.7.3.img \
  --sig ah-gw-pro-2.7.3.img.sig \
  --key aether-release-2026.pub

2. Flash via USB-C recovery

Hold the recessed RECV button while powering the unit, then run the flasher from a computer on the same network:

flash firmwarebash

# gateway must be in recovery mode (slow red LED)
aether-flash \
  --device aetherhome-gw.local \
  --image ah-gw-pro-2.7.3.img \
  --keep-config

The --keep-config flag preserves your site ID, device bindings and automation rules. Unsigned images are rejected by the bootloader — this cannot be disabled.

Configuration

Cloud bridge configuration

The bridge is configured declaratively in YAML (gateway side) and consumed as JSON over the API. Both snippets below are production-ready starting points.

/etc/aetherhome/bridge.yamlYAML

site:
  id: "ah-muc-0421"
  region: "eu-central"
  friendly_name: "Munich Office Westend"

cloud:
  mqtt_host: "mqtt.eu-central.cloud-core.casa"
  mqtt_port: 8883
  tls:
    min_version: "1.3"
    client_cert: "/etc/aetherhome/tls/site.crt"
    client_key: "/etc/aetherhome/tls/site.key"
  reconnect:
    backoff_ms: 1000
    backoff_max_ms: 30000

local_fallback:
  enabled: true
  rules_cache: "/var/lib/aetherhome/rules.cache"
  queue_max_events: 50000

After editing, apply with aether-ctl reload bridge. The gateway validates the file before switching — invalid configs never take effect.

POST /v1/bridges — request bodyJSON

{
  "site_id": "ah-muc-0421",
  "region": "eu-central",
  "protocols": ["matter", "thread", "zigbee"],
  telemetry: {
    interval_hz: 1,
    retention_days: 90
  },
  fallback: {
    enabled: true,
    queue_max_events: 50000
  }
}

Send with Authorization: Bearer . The API responds 201 Created with the effective bridge object and issues short-lived MQTT credentials for the site.

Network

Firewall & port requirements

Everything below is outbound from the gateway. We never require inbound port forwards on your router — remote access is brokered through the cloud edge.

Destination	Port	Protocol	Purpose	Required
`mqtt.eu-central.cloud-core.casa`	`8883`	MQTT over TLS 1.3	Telemetry & commands (mutual TLS)	Yes — core sync
`api.cloud-core.casa`	`443`	HTTPS / WSS	REST API & event streams	Yes — core sync
`dl.cloud-core.casa`	`443`	HTTPS	Firmware & rule-bundle downloads	Recommended
`ntp.eu-central.cloud-core.casa`	`123`	NTP	Time sync for certificate validation	Recommended
Local network (mDNS)	`5353`	UDP	Console discovery (`aetherhome-gw.local`)	Setup only

Strict-firewall environments: gateways operate indefinitely in local fallback mode when only ports 8883 and 443 are blocked, but cloud history and remote access pause until connectivity returns.

Need a hand with your deployment?

Our support engineers answer setup questions Mon–Fri, 09:00–18:00 CET — or browse the FAQ for common topics.

Browse the FAQ

From box to cloud in 15 minutes