Using hyper-calendar

For people using a hyper-calendar someone else is running, or the standalone Android app. If you want to run the server yourself, see Self-hosting.

This part is for people whose calendar is already deployed and who just want to use it from a browser or phone.

Accounts & sign-in

hyper-calendar has its own login screen — no external SSO. On first visit you either register (username + password) or sign in. From the account menu you can then add:

• a passkey — Face ID / fingerprint / device PIN via WebAuthn, for password-free sign-in;
• two-factor authentication — a TOTP code from any authenticator app, with a set of single-use recovery codes to print or store;
• app passwords — separate revocable credentials for connecting CalDAV clients (see Connecting CalDAV clients).

The account menu in the top bar is also where you set an avatar, manage your profile, and sign out. If you'd rather not appear when other users on the instance search for someone to invite, you can hide yourself from the user picker.

Installing the app (PWA)

hyper-calendar is installable as a Progressive Web App, which gives it its own window, an app icon, and offline support.

• Android Chrome: open the site, then use the ⋮ menu → "Install app" (or the install prompt that appears). The app then launches full-screen from your home screen.
• Desktop Chrome/Edge: click the install icon in the address bar.
• Installation only works over HTTPS (or localhost); browsers refuse to register service workers on plain HTTP.

After an update, a small toast offers a "Reload" button to switch to the new version.

Features

• Week view — the core of the app. Tap/click an empty slot to create an event; drag to move; drag the edges to resize. Every gesture works with both mouse and touch, including dragging across day boundaries.

• Other views — Month, Year, and Schedule (agenda) views, with a view switcher and quick navigation between periods.

• Recurring events — daily/weekly/monthly/yearly repeats; editing a repeating event asks whether to change just this occurrence or the whole series.
• Reminders — per-event reminders with per-calendar and global defaults, delivered as push notifications (see Notifications).
• Tasks — lightweight to-dos that live alongside events.
• Multiple calendars — group events into color-coded calendars you can show or hide.
• ICS subscriptions — subscribe to external .ics calendar feeds (holidays, sports schedules, etc.), refreshed automatically.
• CalDAV, both directions — other apps (Thunderbird, Apple Calendar, DAVx5) can read and write your calendars over the built-in CalDAV server, and a calendar can also be linked to a remote CalDAV collection on Nextcloud, Radicale or Fastmail and kept in step two ways.
• End-to-end encryption — mark a calendar encrypted and its titles, descriptions, locations and attachments are encrypted in your browser under your passphrase; the server only ever stores ciphertext. Search still works, because the app sends a scrambled index the server can match without reading. Times and attendees stay unencrypted — see SECURITY.md.
• Sharing & collaboration — invite guests to events, collect RSVPs, and use the "find a time" overlay to see opaque free/busy across people without exposing their event details.
• Import & export — .ics in and out, plus a native .hypercalendar file that round-trips everything the ICS format can't carry.
• Attachments & links — attach files to events; URLs and addresses in event text become clickable (addresses open in maps).
• Search — find events quickly across your calendars.
• Voice entry — the mic button transcribes speech into a new event entirely on-device (offline Vosk model, no API keys). If the model isn't installed the app still works normally and the mic just reports it couldn't load.
• Trash — deleted events go to a recoverable trash before they're gone.
• Keyboard shortcuts — press ? for the cheat sheet; shortcuts are customizable in Settings.

Offline behavior

• The app shell is precached, so it opens offline.
• Recently viewed weeks render offline (GET /api/events uses a network-first strategy with a short timeout).
• Changes you make offline are queued locally and synced when you reconnect. If the same event changed on the server in the meantime, a conflict prompt lets you resolve it field by field.

Notifications

Reminders are delivered via Web Push, so they fire on desktop and on the installed Android PWA even when the app is closed. Enable them per device from Settings → Notifications (this asks for browser permission and registers the device). Push requires a secure origin (HTTPS or localhost), and on iOS the app must be installed to the Home Screen (iOS 16.4+) first. If the server operator hasn't configured push, the toggle reports that it's unavailable.

Version, and reporting a problem

The account menu → About shows the version you're running, which build of the Android app it is, and which of the three deployment modes you're in. That last one matters more than it sounds: the modes are different backends running the same code, so a bug in one often doesn't exist in the others.

Send feedback, in the same menu, writes the report for you. Describe what happened, and it fills in the version, mode, browser, locale, timezone and window size — the details a report usually can't be reproduced without — then opens the issue tracker with all of it prefilled.

Two things to know before you use it:

• It opens your browser and needs a GitLab account. Nothing is sent by the app itself; you review the issue and submit it. The standalone Android app makes no network request of its own for this.
• The issue is public. The details are shown in an editable box before you go anywhere, so delete anything you'd rather not publish, and keep event titles, passwords and your server's address out of the description.

No GitLab account? Email the address in the README instead — that becomes a confidential ticket.

Security vulnerabilities go somewhere else entirely — see the security policy. Don't put them in a public issue.

---