Mac mini Edge Relay — Implementation Guide

Last Verified: February 2026
Canonical implementation: ../archety-edge

The edge relay is implemented as a Node/TypeScript application that: - polls the macOS Messages database for new iMessages - sends outbound messages via AppleScript / helper tooling - maintains local SQLite state for scheduling/rules/plan context - communicates with this backend via /edge/message, /photo/upload, and optionally /edge/ws

---

Quick start (recommended)

Follow the edge repo docs: - ../archety-edge/README.md - ../archety-edge/docs/setup/GETTING_STARTED.md - ../archety-edge/docs/setup/CONFIGURATION.md

---

Backend integration checklist

1. Backend environment variables set (Railway):
2. EDGE_SECRET

3. ENVIRONMENT (set to production in prod)

4. Edge .env set on the Mac mini (not committed):

5. EDGE_SECRET (must match backend)

6. Edge config.yaml points at the backend:

7. backend.url: https://api.ikiro.ai (or the appropriate env URL)

8. Confirm endpoints:

9. POST /edge/message works
10. POST /photo/upload works
11. GET /edge/ws connects (optional, but recommended)

Protocol reference: - docs/architecture/WEBSOCKET_PROTOCOL.md