Keeper.sh

About

Keeper.sh is a simple & open-source calendar syncing tool. It allows you to pull events from your Google Calendar, Outlook, iCloud, Fastmail, CalDAV server, or remotely hosted iCal and ICS links, and push them to one or many calendars so the time slots can align across them all. Google, Outlook, iCloud, Fastmail, and CalDAV are first-class integrations that can each be used as a source or as a destination, while iCal and ICS links are pull-only. It also serves as a global MCP server and API for you or your agents to manage all your calendars from one convenient interface.

The recommended way to run it is the hosted version at keeper.sh: the same code, minus the server, the domain, the upgrades, the backups and the Google and Microsoft sign-in apps you would otherwise register yourself. Self-hosting is a first-class path and every Pro feature is included when you self-host — that is not a trial, and it is not going away. It costs you the upkeep instead of the $5.

Features

• First-class Google Calendar, Outlook, iCloud, Fastmail, and CalDAV integrations, each usable as a source or a destination
• Pull-only ingestion of remotely hosted iCal and ICS links
• Incremental syncing on Google and Outlook using provider sync tokens rather than refetching everything
• Event content agnostic syncing engine
• Push aggregate events to one or more calendars
• Per-source privacy controls to strip event names, descriptions, and locations, replacing the title with a {{calendar_name}} or {{event_name}} template
• REST API under /api/v1 authenticated with API tokens
• MCP (Model Context Protocol) server for AI agent calendar access
• Combined iCal feed you can subscribe to from any calendar app
• Open source under AGPL-3.0
• Easy to self-host
• Easy-to-purge remote events

Bug Reports & Feature Requests

If you encounter a bug or have an idea for a feature, you may open an issue on GitHub and it will be triaged and addressed as soon as possible.

Contributing

High-value and high-quality contributions are appreciated. Before working on large features you intend to see merged, please open an issue first to discuss beforehand.

Local Development

The dev environment runs behind HTTPS at https://keeper.localhost using a Caddy reverse proxy with automatic TLS. The .localhost TLD resolves to 127.0.0.1 automatically per RFC 6761 — no /etc/hosts entry is needed.

Prerequisites

• Bun (v1.3.11+)
• Docker & Docker Compose

Getting Started

bun install

Generate and Trust a Root CA

The dev environment runs behind HTTPS via Caddy. You need to generate a local root certificate authority and trust it so your browser accepts the certificate.

mkdir -p .pki

openssl req -x509 -new -nodes \ -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \ -keyout .pki/root.key -out .pki/root.crt \ -days 3650 -subj "/CN=Keeper.sh CA"

Then trust it on your platform:

macOS

sudo security add-trusted-cert -d -r trustRoot \

-k /Library/Keychains/System.keychain .pki/root.crt

Linux

sudo cp .pki/root.crt /usr/local/share/ca-certificates/keeper-dev-root.crt

sudo update-ca-certificates

Start the Dev Environment

bun dev

This starts PostgreSQL, Redis, and a Caddy reverse proxy via Docker Compose, along with the API, web, MCP, cron, and worker services locally. Once running, open https://keeper.localhost.

Architecture

Qs

Why does this exist?

Because I needed it. Ever since starting Sedna—the AI governance platform—I've had to work across three calendars. One for my business, one for work, and one for personal.

Meetings have landed on top of one-another a frustratingly high number of times.

Why not use _this other service_?

Use one if it already works for you. This one exists because of the two things I kept hitting: events deleted at the source that stayed on the destination forever, and no way to read the code that was handling my calendar.

Both are addressed by design here. A deletion is tracked by a mapping row that outlives the event it pointed at, so the remote copy still gets removed on a later pass, and the cleanup sweep only ever touches events Keeper.sh created — it will not delete an event you made yourself. And the engine is AGPL-3.0, so you can check that claim rather than take it.

How does the syncing engine work?

• If we have a local event but no corresponding "source → destination" mapping for an event, we push the event to the destination calendar.
• If we have a mapping for an event, but the source ID is not present on the source any longer, we delete the event from the destination.
• Any events with markers of having been created by Keeper.sh, but with no corresponding local tracking, we remove it. This is only done for backwards compatibility.

Events are flagged as having been created by Keeper.sh either using a @keeper.sh suffix on the remote UID, or in the case of a platform like Outlook that doesn't support custom UIDs, we just put it in a "keeper.sh" category.

How is the syncing split up?

There are two halves, and they run on separate schedules.

Ingestion pulls from your sources into Keeper.sh's own database once a minute, regardless of plan. Google and Outlook are fetched incrementally using the provider's own sync token and delta link respectively, so a run only asks for what changed since the last one. CalDAV, iCloud, and Fastmail are refetched and diffed against the event state Keeper.sh already has stored, and iCal/ICS links are refetched and diffed against the last stored snapshot.

Pushing to destinations is what the refresh interval in the pricing table refers to. The cron service enqueues a job per destination onto a Redis-backed queue every minute for Pro and every thirty minutes for free, and the worker service reconciles the destination calendar. This is polling on our side rather than provider push notifications, so nothing needs to reach your instance from the outside.

Neither half is schedule-only. POST /api/v1/sync, or trigger_sync over MCP, clears the ingest backoff so your sources are re-polled on the next pass and enqueues the push half straight away, throttled to one request per minute per user so a client cannot hammer your providers. A calendar paused with pause_sync is skipped by both halves until it is resumed.

Cloud Hosted

This is the version I would point most people at, including people perfectly capable of running it themselves. It is the same engine on hardware I keep running, so the hours go into your calendar instead of your infrastructure — and paying for it is what funds the work on both versions.

Head to keeper.sh to get started with the cloud-hosted version.

The two limits that bite first are counted separately. A linked account is one connected Google, Outlook, iCloud, Fastmail, or CalDAV account, or one iCal/ICS subscription, and free is capped at two of them however many calendars each exposes. A sync mapping is one source calendar wired to one destination calendar, and free is capped at three, so a single source fanning out to three destinations uses the whole allowance. The refresh interval is how often Keeper.sh pushes to your destinations; ingestion from your sources runs every minute on every plan.

Self Hosted

By hosting Keeper.sh yourself, you are on the Pro tier by default — every Pro feature, no subscription — and you can guarantee data governance and autonomy, and it's fun. What it costs instead is a server, a domain, upgrades, backups, your own Google and Microsoft OAuth apps, and being the person paged when it stops. If you'll be self-hosting, please consider supporting me and development of the project by sponsoring me on GitHub.

There are seven images currently available: two designed for convenience, and five that serve the granular underlying services. If you have no reason to prefer otherwise, start with keeper-standalone behind a reverse proxy — it is the path with the fewest moving parts to get wrong.

[!NOTE]

Migrating from a previous version? If you are upgrading from the older Next.js-based release, see the migration guide for environment variable changes. The new web server will also print a migration notice at startup if it detects old environment variables.

Environment Variables

| DATABASE_URL | api, cron, worker, mcp | PostgreSQL connection URL.

e.g. postgres://user:pass@postgres:5432/keeper | | REDIS_URL | api, cron, worker | Redis connection URL. Must be the same Redis instance across all services.

e.g. redis://redis:6379 | | DATABASE_POOL_MAX | api, cron, worker, mcp | Optional. Maximum Postgres connections the service's pool opens. Defaults to 10 per service, and the keeper-standalone and keeper-services images ship a smaller per-service value sized to the Postgres they run against. Every co-located service adds its own pool, so the sum of these plus CRON_FLUSH_POOL_MAX must stay under your Postgres max_connections with room left to connect for yourself.

e.g. 15 | | CRON_FLUSH_POOL_MAX | cron | Optional. Size of the second pool cron holds for ingest writes, separate from and additional to DATABASE_POOL_MAX. Defaults to 16; the bundled images ship 8.

e.g. 16 | | RUN_MIGRATIONS | api | Optional. Set to false to skip applying database migrations when the API container starts, for deployments that run them as a separate step before rolling the services. Defaults to true.<b