Skip to content

Calendar and scheduling

Control Center connects to Google Calendar so your day sits alongside your fleet. It syncs your events, shows them in month, week, day and agenda views, lets you book, move, answer and delete events, warns you before a meeting starts and turns any event into a recorded, summarised meeting.

Only what you do yourself. You can answer an invitation, book an event (drag across the time grid, or the + button), move or stretch one on the grid and delete one. Each change is made by the server with your own account’s sign-in, on your own calendars, and the server refuses an event on another member’s account or on a calendar shared with you read-only. Google emails the guests, as it would from Google Calendar. Only your own events and the ones you organise move: a guest’s change would leave everyone else at the old time. Moving or deleting one occurrence of a recurring event leaves the rest of the series.

Every connect, through Connect or the server’s own Google client, requests calendar.events (read and change events) and calendar.calendarlist.readonly (see which calendars the account has) plus openid email. The server refuses a sign-in that comes back with a different set, so an account connected with the earlier read-only scope must be reconnected.

Events are synced into the workspace’s own database on the server (<dataDir>/<workspaceId>/workspace.db) and rendered by every client over RPC. No client holds a Google credential.

Calendar accounts are workspace-scoped, like everything else in Control Center, and each belongs to the member who connected it. Each workspace connects its own Google accounts and one workspace’s events and credentials are never visible from another. Two members who connect the same Google address get two accounts. Switching workspaces switches which calendars you see.

A workspace can connect multiple Google accounts, such as a work account and a personal one and their events are merged into the same views.

Connecting is a browser sign-in, and the server finishes it. Which client runs it is the server owner’s choice:

  • The server’s own Google client. A Web application client registered with the redirect <server origin>/oauth/google/callback. Google sends the browser straight back to the server, so the browser must be able to reach it
  • Control Center Connect. Google sends the browser back to Connect, which shows an 8-character code and a control-center:// link. The person types the code into the app, or follows the link, and the server claims the sign-in with it. The server needs no public address for this, which is how a headless server on a private network connects calendars

An own client always takes precedence. A client id without its secret is an unfinished setup and refuses sign-ins rather than falling back to Connect.

Credentials never leave the server. They are written to the server’s secrets.json in its data directory, keyed google_google:<workspaceId>:<userId>:<email>, alongside the databases and under the same host-filesystem trust boundary. An own-client sign-in stores its access and refresh tokens. A Connect sign-in stores only a sealed credential that Connect opens for this server alone; the access token stays in memory. The server refreshes access automatically and, when Google permanently invalidates an account (a revoked or long-expired session), publishes CalendarAuthExpired and surfaces a reconnect banner instead of failing silently. A sign-in this server can no longer use (issued by a different own client, or sealed for a different install or Connect) is cleared the next time it is read and shows the same banner.

No build carries Google credentials. The server’s client comes from Settings → Server → Single sign-on → Provider apps or the server’s .env file (GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET). There is deliberately no command-line flag: a secret on a command line is readable through ps, and the server refuses to start when the secret is exported in its process environment.

For running your own Google project, see Connect a Google Calendar.

The server pulls a rolling window of each connected account’s events — every calendar on the account, not just the primary — every two minutes, plus on demand (start, connect, manual refresh). The short cadence is affordable because the sweep is incremental: each calendar carries its own sync token, so an unchanged calendar costs one near-empty response rather than re-fetching a five-month window.

Recurring events are expanded server-side, so no client ever parses a recurrence rule. Navigating to a month outside the current window lazily loads that range. Deleted or moved-out-of-range events are reconciled away on the next sync.

View What it shows
Month A full month grid (powered by the kalender package)
Week A week’s timed events in a time-grid
Day A single day’s timed events in a time-grid
Agenda A scrollable list of upcoming events

Open the calendar at /calendar; selecting an event opens its detail at /calendar/:eventId. The view you pick is stored in that client’s own preferences, so it does not follow you to another device.

A per-minute scheduler scans for events starting within a configurable lead window and fires a “meeting starting soon” notification (a MeetingStartingSoon domain event). The notification carries the join URL when one is present and clicking it opens the event detail. Alerts are de-duplicated against the event’s alertedAt, so the same meeting never alerts twice, even across restarts and an event whose start passed while the app was closed never replays.

Two limits are easy to trip over. The scheduler runs client-side on the desktop and only for the workspace you currently have open — a workspace you are not in raises no alert. And the web build has no OS-notification pipeline at all, so it raises none either.

From a calendar event you can start a meeting recording seeded with the event’s title. Control Center stores a one-to-one link between the recording and the event, so the meeting’s notes and the calendar entry stay connected without either feature depending on the other.

Start recording & link is desktop-only. On the web client the action reports that recording is unavailable — even though the meetings screen’s own record flow does work in the browser.