ARIA/iris_x_hermes

0 Fork 0

Files

T

ARIA b1c9bac7d8

CI / Gateway plugin tests (push) Successful in 5m19s

Details

CI / Kotlin tests (android host + desktop) (push) Successful in 7m3s

Details

docs+plugin: HTTP-only transport cleanup, install guide, review fixes

- docs/install.md: new end-to-end guide for non-technical users
  (gateway install, app install, LAN/TLS/remote connection, push,
  options, troubleshooting); docs/setup.md now points to it
- README: new 'Install the gateway' section; pairing section updated
  for HTTP transport (8791, QR scan on Android)
- rename IRIS_WS_HOST -> IRIS_HTTP_HOST (clean rename, no compat
  fallback); drop dead DEFAULT_PORT=8790
- setup.py: advertise https:// in the printed/QR server URL when
  IRIS_HTTP_CERT is set
- ws_probe.py/e2e.py: default --url http://127.0.0.1:8791, env
  IRIS_WS_URL -> IRIS_HTTP_URL, honor explicit port + https scheme
- plugin.yaml: IRIS_HTTP_* env names, description no longer says
  'WebSocket server'
- docs 03/09/12/19: fix stale WS-era refs (ws_server.py cites,
  8790 smoke test, WSS->HTTPS, 'HTTP fallback' reframed as the
  only transport)
- AGENTS.md: symlink name android -> iris (matches actual install)
- test: adapter reads IRIS_HTTP_HOST/CERT/KEY from env; legacy
  IRIS_WS_* names are not consulted (95/95 pass)

2026-08-24 22:22:02 +02:00

4.3 KiB

Raw Blame History

12 — Toolchain Setup

First-time setup on a machine (verified baseline: CachyOS/Arch, pacman, uv present, ADB present, no JDK/SDK/Gradle).

12.1 JDK 17

pacman -S jdk17-openjdk
java -version   # expect 17.x

(Compose Multiplatform + current AGP are happy on JDK 17. Use 17 to match the Android toolchain; 21 also works but 17 is the safe floor.)

12.2 Android SDK

# cmdline-tools
mkdir -p ~/android-sdk/cmdline-tools
cd ~/android-sdk/cmdline-tools
curl -O https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
unzip commandlinetools-linux-*.zip && mv cmdline-tools latest
rm commandlinetools-linux-*.zip

export ANDROID_HOME=$HOME/android-sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools

sdkmanager --licenses
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"

Persist ANDROID_HOME/PATH in ~/.bashrc. ADB is already installed system-wide; platform-tools from the SDK is fine too (whichever is first on PATH).

Create app/local.properties:

sdk.dir=/home/<you>/android-sdk

12.3 Gradle

No system install — use the project wrapper:

cd app
./gradlew tasks        # first run downloads the wrapper distribution

(The wrapper version is pinned in app/gradle/wrapper/gradle-wrapper.properties.)

12.4 hermes environment (for the plugin + running the gateway)

cd hermes-agent
uv sync                # creates .venv with all core deps (websockets, httpx, …)
source .venv/bin/activate
hermes --version       # sanity

Run the gateway with the plugin:

# install the plugin (dev: symlink)
mkdir -p ~/.hermes/plugins
ln -s "$PWD/../gateway-plugin" ~/.hermes/plugins/iris
hermes gateway status     # should list "iris"
hermes gateway            # run

Tests use hermes's hermetic runner (never bare pytest):
```
scripts/run_tests.sh tests/gateway/test_android.py
```

12.5 Firebase (FCM) — primary push

Create a Firebase project (console.firebase.google.com).
Add an Android app (package = androidApp applicationId, e.g. dev.iris.app). Download google-services.json → app/androidApp/.
Create a service account (Project settings → Service accounts → Generate new private key) → download the JSON. Store its path in IRIS_FCM_SERVICE_ACCOUNT (in ~/.hermes/.env).
The app's FirebaseMessagingService obtains the FCM token at runtime and registers it via hello / fcm.register.

Skip Firebase → the default is already ntfy: leave IRIS_PUSH_BACKEND unset (or set it to ntfy) and configure NTFY_TOPIC / NTFY_SERVER_URL (self-host ntfy or use ntfy.sh). See 08-push.md.

12.6 Environment variables (summary)

Secrets (~/.hermes/.env):

IRIS_TOKEN=<64-hex>
IRIS_PUSH_BACKEND=ntfy           # default; fcm = opt-in (metadata via Google)
IRIS_FCM_SERVICE_ACCOUNT=/path/to/service-account.json
# IRIS_FCM_SERVER_KEY=<legacy key>   # fallback if no service account
# NTFY_TOPIC=iris-push                  # when ntfy
# NTFY_SERVER_URL=https://ntfy.sh
# IRIS_HTTP_CERT=/path/cert.pem      # HTTPS
# IRIS_HTTP_KEY=/path/key.pem

Behavioral (~/.hermes/config.yaml):

gateway:
  platforms:
    iris:
      enabled: true
      extra:
        host: 127.0.0.1        # 0.0.0.0 for LAN
        http_port: 8791
        home_channel: default
        push_backend: fcm
        outbox_retention_hours: 72
        max_upload_bytes: 104857600   # 100 MB
display:
  platforms:
    iris:
      show_reasoning: true
      reasoning_style: code
      streaming: true
      tool_progress: all       # gateway sends full data; app controls display

12.7 Verify the stack (smoke test)

# 1. gateway up with plugin
hermes gateway status | grep -i iris

# 2. the HTTP server answers (unauthenticated liveness)
curl -s http://127.0.0.1:8791/v1/health
# -> {"ok": true}

# 3. a frame round-trip with the pairing token
curl -s -X POST http://127.0.0.1:8791/v1/frame \
  -H "Authorization: Bearer <IRIS_TOKEN>" -H "X-Iris-Device: probe" \
  -H "Content-Type: application/json" \
  -d '{"v":1,"type":"commands.catalog","id":1,"payload":{}}'

Expect {"ok": true} from the health probe and a commands.catalog reply frame from the POST. If you get 401, the token/host/port is wrong.

4.3 KiB Raw Blame History