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.
What it changes on Google
Section titled “What it changes on Google”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.
Per-workspace accounts
Section titled “Per-workspace accounts”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.
How sign-in reaches the server
Section titled “How sign-in reaches the server”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.
Meeting alerts
Section titled “Meeting alerts”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.
Record and link
Section titled “Record and link”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.
See also
Section titled “See also”- Meetings and transcription: what happens after you start a recording
- Workspaces and isolation: why calendar accounts are per-workspace
- Domain events:
MeetingStartingSoonandCalendarAuthExpired - Connect a Google Calendar
- Record and summarise a meeting