homeassistant-stelloauth-addon/stelloauth/DOCS.md

Installation and operation

1. Go to Settings → Apps → Install app → ⋮ → Repositories and add this exact URL: https://git.radixadm.dk/dennis/homeassistant-stelloauth-addon.git.

2. Install Stelloauth, enable Start on boot and Watchdog, then start the app. Home Assistant builds a local image from source for the selected amd64 or aarch64 architecture. This repository does not publish a prebuilt image.

3. Wait for the app log to show these five readiness messages in order:

   Cleaning CloakBrowser profiles
   Starting CloakBrowser
   CloakBrowser ready
   Starting Stelloauth
   Stelloauth listening on 0.0.0.0:8080
   

4. Keep the host port disabled during normal operation. For brief troubleshooting, map 8080/tcp to host port 8080. Then check http://192.168.1.20:8080/ or the worker endpoint at http://192.168.1.20:8080/worker. Disable the port mapping again when you finish. The worker endpoint receives MyOpel details and has no separate authentication.

5. Open the Stellantis Vehicles integration's configuration and set Login service URL to exactly http://0031621f-stelloauth:8080/worker. The integration does not append /worker, so include the full path.

6. Select Brand: Opel and Country: DK, then complete the integration's OAuth setup with your MyOpel details.

   When asked for a security PIN, enter the four-digit PIN you chose when activating Remote Control in the MyOpel app. Do not wait for MyOpel to send you a new PIN; the SMS verification code is separate.

7. The app provides three options:

   • queue_timeout: how long a login attempt may wait for the single session.
   • rate_limit_count: the maximum number of login attempts allowed in each period.
   • rate_limit_duration: the length of the login rate-limit period.

   CLOAK_MAX_SESSIONS is fixed at one because CloakBrowser's free tier allows one concurrent login. Additional attempts wait in the queue.

8. Each OAuth attempt gets a temporary profile under /tmp/cloakserve. CloakBrowser removes inactive browser processes after 30 seconds, and the process manager removes old profiles at startup. Credentials, cookies, tokens, and OAuth codes are not stored in /data. CDP listens only on the loopback address 127.0.0.1:9222. Logs use fixed, redacted messages and do not include email addresses, passwords, URLs, codes, or tokens.

9. Measurements from a real linux/amd64 run under Rosetta:

   • Image: 2,571,693,650 bytes (2.571 GB decimal / 2,452.56 MiB).
   • Documented Task 4 measurement: 121.5 MiB.
   • Stop time: about 9.3 seconds.
   • The amd64 runtime passed under Rosetta; the aarch64 build passed.

10. Troubleshooting and removal:

    • If a readiness message is missing, check for a timeout. CloakBrowser has 60 seconds and Stelloauth has 30 seconds. Fix the cause, then restart the app.
    • An invalid or disallowed authorize URL returns HTTP 400.
    • Too many login attempts return HTTP 429; wait for the configured rate-limit period.
    • If the repository URL or hostname changes, the Supervisor repository ID and 0031621f-stelloauth hostname also change. Calculate and use the new internal URL.
    • If disk space is low, check available space and remove unneeded images or backups through Supervisor before building again.
    • If the internal URL cannot be reached, use the temporary port check from step 4, then disable the port mapping again.
    • To remove the app, go to Settings → Apps → Stelloauth → Uninstall. Supervisor stops the container and removes the app's local data. If you no longer need the repository, remove it from Settings → Apps → Install app → ⋮ → Repositories as well.

Sources and licenses

App version 0.1.0 builds Stelloauth v0.6.0 from commit 367d4f8c02a3b072c59142c49dffc129edc8548b and uses the official CloakBrowser 0.5.10 image at OCI index digest sha256:2ed5b2d047cbdde22cde7ef1a796526c716aadaa5bccbe1db5ade49282b64a76. The repository's original files and patches are licensed under the MIT License. The proprietary CloakBrowser binary remains subject to the separate CloakBrowser Binary License. It is not licensed under MIT or redistributed by this repository.