Meridian
Declarative, Kubernetes-first calendar sync. Meridian mirrors events between your own calendars as rule-based, transformed copies, configured entirely as code and running as a single stateless pod. Google Calendar and CalDAV, in any combination.
The canonical example: every appointment on your private calendar shows up as an anonymous Busy block on your work calendar. Colleagues see when you're free. They don't see why you aren't.
Status: dogfood. Meridian runs unattended on the maintainer's homelab, mirroring real calendars around the clock.
It began as one person's use case, and generalizing past that was the point. Rules, filters and transforms are built to compose, so if your setup differs the difference should land in configuration rather than in a fork.
What a config looks like
instance: home # unique per deployment, and never change it once copies exist
accounts:
- name: personal
type: google
clientIDEnv: MERIDIAN_GOOGLE_CLIENT_ID # names of env vars, never secrets
clientSecretEnv: MERIDIAN_GOOGLE_CLIENT_SECRET
refreshTokenEnv: MERIDIAN_GOOGLE_REFRESH_TOKEN
calendars:
- name: private
id: primary
- name: work
id: [email protected]
rules:
- id: private-to-work
from: personal/private
to: [personal/work]
filter:
weekdays: [mon, tue, wed, thu, fri]
window: "08:00-18:00"
timezone: Europe/Zurich
skipAllDay: true
transform:
title: Busy
description: drop
location: drop
That's the whole surface: accounts, the calendars they expose, and rules pointing one at another. meridian validate checks it without touching a credential or a provider, so it runs in CI on every change.
Filters also take a CEL predicate (when: 'event.durationMinutes >= 30'), and the three string transforms take Go templates (title: "» {{ .Title }}"). Worked examples are in Write sync rules.
Is this for you?
Good fit if:
- You already run Kubernetes and want sync rules living in Git alongside everything else you deploy.
- You want one-way mirrors with transformed content, like stripping titles down to "Busy".
- You're syncing your own calendars, not running a service for other people.
Not a fit if:
- You want scheduling: finding meeting slots, negotiating free/busy, moving things around. Meridian copies events and holds no opinions about how you should spend your week.
- You need a genuine two-way merge, where edits on either side flow back.
- You need multi-user or multi-tenant operation from one install.
- You need Exchange, Outlook, or Microsoft 365. Google Calendar and CalDAV only.
Limitations has the full list, and it's worth two minutes before you invest more.
How it works
Level-triggered reconciliation, the way a Kubernetes controller works. Each cycle fetches every event in a rolling window from your sources and destinations, computes the copies the rules call for, and makes the destinations match: create, update, or delete.
- No database. The calendars hold the state. A crashed pod, a restored backup and a rewritten config all converge the same way.
- Copies carry an ownership marker naming the instance and rule that created them. Meridian only ever touches its own. Your events and other tools' events are invisible to it.
- Change detection is a content hash stored in that marker, so provider-side normalization can't trigger spurious updates.
Next
| |
|---|
| Get started | One rule syncing end to end on your laptop, in a few minutes. |
| Deploy | Helm chart, config modes, metrics. |
| Reference | Every config field, CLI flag and metric, generated from the source. |
| FAQ | Why there's no database, whether it's safe to point at a calendar you use. |
| Design | What each part of the engine guarantees, and what it refuses to do. |
Contributing
Issues and pull requests are welcome. CONTRIBUTING.md covers the build commands, the commit convention the release pipeline depends on, and what a change to the engine is expected to come with. Be civil about it (code of conduct).
Found a security problem? SECURITY.md has private reporting and the trust boundary — what Meridian does with calendar credentials, and what it deliberately never touches.
License
MIT.
