{"id":50364775,"url":"https://github.com/iggut/hermes-courier","last_synced_at":"2026-05-30T03:03:33.902Z","repository":{"id":352514975,"uuid":"1215437692","full_name":"iggut/hermes-courier","owner":"iggut","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T03:58:43.000Z","size":20207,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T05:24:02.529Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iggut.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T22:56:15.000Z","updated_at":"2026-04-28T03:58:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iggut/hermes-courier","commit_stats":null,"previous_names":["iggut/hermes-courier"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/iggut/hermes-courier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iggut%2Fhermes-courier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iggut%2Fhermes-courier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iggut%2Fhermes-courier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iggut%2Fhermes-courier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iggut","download_url":"https://codeload.github.com/iggut/hermes-courier/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iggut%2Fhermes-courier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33678271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-30T03:03:33.828Z","updated_at":"2026-05-30T03:03:33.894Z","avatar_url":"https://github.com/iggut.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Hermes Courier\n\n**Hermes Courier** is a secure Android and iOS companion app for controlling [Hermes Agent](https://github.com/iggut/hermes-agent) from your phone.\nIt is designed for mobile-first operation while preserving the power of the Hermes web experience — and adding a few things only a phone can do well.\n\nBuilt with the same spirit as [hermes-webui](https://github.com/nesquena/hermes-webui), Hermes Courier aims to provide feature parity with the web UI and extend it with stronger mobile security, faster approvals, and device-native workflows.\n\n## Why it exists\n\nHermes is powerful when you're at a desk, but you also need a safe way to:\n\n- check what your agent is doing\n- approve or deny sensitive actions\n- jump into a live conversation\n- review memory and recent activity\n- manage automations and scheduled tasks\n- stay connected while away from your computer\n\nHermes Courier is built for those moments.\n\n## Core goals\n\n- **All Hermes WebUI features, on mobile**\n- **Stronger security by default**\n- **Fast, one-handed control**\n- **Clear status and intervention tools**\n- **Companion-level visibility without exposing raw secrets**\n\n## CI / builds\n\n- Automated checks run on push and pull request in `.github/workflows/ci.yml`.\n- Manual Android builds are available on demand in `.github/workflows/android-on-demand-build.yml`.\n- The on-demand workflow produces a debug APK artifact from GitHub Actions.\n\n## Validation quickstart\n\n- Android unit tests (JDK 17 or 21): `cd android \u0026\u0026 ./gradlew :app:testDebugUnitTest --no-daemon`\n- iOS unit tests (macOS + Xcode required): see `ios/README.md` for `xcodegen generate` + `xcodebuild ... -only-testing:HermesCourierTests test`\n- Live gateway smoke pass: `./scripts/live-gateway-smoke-test.sh`\n\n### Live smoke environment\n\n- Required: `HERMES_LIVE_GATEWAY_BASE_URL`\n- Recommended auth: `HERMES_LIVE_GATEWAY_BEARER_TOKEN`\n- Optional: `HERMES_LIVE_GATEWAY_AUTH_MODE=auto|token` (default `auto`)\n- Optional: `HERMES_LIVE_GATEWAY_ALLOW_MUTATING=1` to exercise POST actions (approval decision, conversation send, session-control candidates)\n- Optional: `HERMES_LIVE_GATEWAY_SESSION_ID`, `HERMES_LIVE_GATEWAY_APPROVAL_ID` to force specific IDs\n- Optional TLS/dev modes: `HERMES_LIVE_GATEWAY_CURL_INSECURE=1` and `HERMES_LIVE_GATEWAY_TIMEOUT_SECONDS=\u003cseconds\u003e`\n\nThe smoke script reports each endpoint as `ok`, `failed`, `unsupported`, `drift`, or `skipped`, so partial environments do not produce fake full-pass results.\n\n## Planned features\n\n### WebUI parity\n\n- live chat and conversation history\n- streaming responses and tool execution updates\n- model and provider controls\n- session browsing and search\n- memory visibility and recall tools\n- cron / scheduled task management\n- logs, errors, and activity views\n- approvals for sensitive commands\n- multi-platform message routing\n\n### Mobile-first enhancements\n\n- biometric authentication for app unlock and approvals\n- hardware-backed secure storage for tokens and session secrets\n- push notifications for approvals, alerts, and task completion\n- lock-screen-safe notification controls\n- quick actions and deep links for common agent tasks\n- offline-safe drafts and queued actions\n- compact incident view for fast triage\n- voice input and voice note support\n- mobile-friendly session cards and swipe actions\n\n## Security model\n\nSecurity is a first-class feature.\n\nPlanned protections include:\n\n- end-to-end encrypted transport to the Hermes backend\n- device-bound credentials and short-lived session tokens\n- biometric gating for sensitive actions\n- local secret storage using Android Keystore / hardware-backed APIs where available\n- explicit user confirmation for risky operations\n- minimal exposure of raw tokens, logs, and private memory on screen\n\n## Architecture\n\n- **Android app:** Kotlin + Jetpack Compose with an embedded Python runtime (Chaquopy). The Android app runs the Hermes-WebUI backend natively, acting as its own local server.\n- **iOS app:** Swift + SwiftUI. Operates as a thin client connecting to a remote Hermes gateway.\n- **Auth layer:** secure session bootstrap with short-lived tokens\n- **Transport:** HTTPS / secure websocket channel to Hermes (local to device on Android, remote on iOS)\n- **State:** local encrypted cache for offline-safe views\n- **Notification layer:** push events for approvals, status, and completion alerts\n- **Backend companion:** Hermes Agent + the companion routing/memory stack. On Android, this stack is embedded directly within the app.\n\n## Chaquopy Integration and Deployment\n\nThe Android application leverages [Chaquopy](https://chaquo.com/chaquopy/) to embed a Python runtime. This means the `hermes-webui` backend runs natively directly on the Android device.\n\n**Deployment Implications:**\n- **No Separate Server:** Android users do not need to host or point to a remote gateway URL. The backend runs locally.\n- **Self-Contained:** All logic, automations, and routing usually handled by the remote server happen inside the app.\n- **Embedded WebUI:** The UI is driven by the internal Python environment serving the API surface directly to the local frontend.\n\n## API Surface\n\nBecause Android embeds the backend, the API surface provided by the embedded WebUI is served locally on the device. The local HTTP server provides:\n\n- `GET /v1/dashboard`\n- `GET /v1/sessions`\n- `POST /v1/sessions/{sessionId}/actions`\n- `GET /v1/approvals`\n- `GET /v1/conversation`\n- Real-time events and log streaming\n- (And other standard WebUI endpoints, all handled internally via Chaquopy)\n\nFor a complete list of endpoints, refer to the OpenAPI contract. On Android, these calls never leave the device.\n\n## Configuration\n\nSince the Android backend is embedded:\n- **Android:** Users do not need to point at a remote gateway URL. The embedded Chaquopy backend is initialized automatically and binds to a local port (e.g. localhost).\n- **iOS:** Still requires pointing to a remote gateway URL or an accessible internal network address.\n\n## Repository structure\n\n- `android/` — Jetpack Compose Android app embedded with Python/Chaquopy backend\n- `ios/` — SwiftUI iOS app generated from `ios/project.yml` (XcodeGen)\n- `shared/contract/` — OpenAPI contract and path definitions shared by both clients\n- `user_webui/` — Submodule for the embedded Python web interface logic\n\n## Roadmap\n\n### Phase 1 — Foundation\n\n- establish repo structure\n- define API contract with Hermes\n- scaffold Android and iOS clients\n- prototype secure gateway auth\n- wire basic session browsing and approvals\n\n### Phase 2 — Core usage\n\n- real websocket / event stream support\n- secure token persistence\n- approval workflows\n- session history and search\n- settings and gateway management\n\n### Phase 3 — Mobile polish\n\n- biometrics and device attestation\n- push notifications\n- offline-safe queueing\n- dark mode polish and accessibility improvements\n- launch-ready onboarding\n\n## Status\n\nBoth mobile apps implement the shared contract paths (dashboard, sessions, approvals, conversation, approval decisions, and `/v1/events` realtime). The Android app is now successfully bootstrapped to embed the Python backend natively via Chaquopy. Local/demo transports and settings flows are in place; production gateway hardening (pinning, attestation, full backend) remains on the roadmap above.\n\n**UI navigation:** there is no separate “chat” tab — the conversation feed is embedded in **Dashboard** on both platforms (tabs: Dashboard, Sessions, Approvals, Settings).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figgut%2Fhermes-courier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figgut%2Fhermes-courier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figgut%2Fhermes-courier/lists"}