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.