TomSparkCal: complete setup, sharing, phone and backup guide
Posted by Chris
TomSparkCal: complete setup, sharing, phone and backup guide TomSparkCal is a private calendar for people who want to add the appointment and get on with their day. Paste a message or dictate a plan, check the suggested date and time, and save. You do not need to begin by filling out a long appointment form. This guide covers the browser app available now. The native mobile app is coming soon. Sections describing iPhone Shortcuts, connected Apple/Google calendars and native notifications are for the iOS build when you have access to it; installing the website on your Home Screen does not add those native features. 1. Choose where your calendar lives | Option | What you need | What synchronizes | Best fit | | --- | --- | --- | --- | | Local only | A browser; no account | Nothing leaves for calendar sync | One device, simplest start | | Your own SparkBox | SparkBox 1.6.689+, TomSparkCal installed, HTTPS access | Together plans between invited devices | A household controlling its own server | | Hosted with SparkBox Ultimate | An active Ultimate key and a calendar account | Your TomSparkCal account plans across your devices, plus invited family sharing | Sync without running a server | The self-hosted SparkBox module is free. Ultimate includes hosted calendar sync at no extra charge. These options do not include unlimited cloud AI. Basic text parsing runs locally; optional Haiku is a separate, owner-configured service using that household's own API key. Open the browser app from the welcome post in the TomSparkCal community. If your SparkBox hosts the app, use the Open button on its TomSparkCal card instead. Always return to the same browser address: browser storage belongs to that address and browser profile. 2. Make your first plan before setting up anything else 1. Open the calendar and choose the add-plan button. 2. Type a simple example such as Coffee with Alex tomorrow at 9am. 3. Choose Personal, Together or Work. Together is the shared category; the others are for your own plans. 4. Preview the result. Check the day, month, year, start time, end time and whether it is an all-day plan. 5. Confirm to save, then find the appointment in the monthly calendar. 6. Open it again if you need to edit it or remove the test. For several appointments, put each event on its own line. An explicit month name is easier to verify than an ambiguous numeric date. If a phrase is interpreted incorrectly, rewrite it clearly and preview again. The preview is there for a reason: date interpretation can make mistakes, especially around relative dates, trips, midnight and time zones. Your device's time zone is shown beneath the calendar. A plan described as “Friday at 7” needs a.m./p.m. context; “Friday at 7pm” is better. Review travel appointments against the intended local time rather than assuming text interpretation knows your travel schedule. 3. Stay local with no account Open Settings → Where your calendar lives and select Local only. You can keep using text entry, local parsing, the monthly view and calendar exports without creating an account. Local means this browser or installed app holds your plans. Opening another browser, another profile, a private window or another phone will not automatically show them. Clearing website data can remove plans and stored keys. Browser storage is not an encrypted vault: protect the device itself and keep an exported backup. After loading the browser app online, its cached app files may support offline reopening. Browser cleanup can remove those files. Before relying on it while travelling, open it once offline on the actual device and check that your plans are present. No account is needed just to try the calendar. 4. Use hosted sync included with Ultimate 1. In the browser containing the plans you want to keep, open Settings → Where your calendar lives. 2. Choose Hosted with SparkBox Ultimate, then Create account. 3. Enter your active Ultimate license and choose a username. 4. Save the generated recovery key in a password manager or another private place outside this browser. 5. Leave the calendar open until it reports that the encrypted account is up to date. 6. On your second device, open the same browser app and choose the hosted option, then Sign in. 7. Enter the same username and recovery key. Do not create another account for your own second device. 8. Keep both calendars open briefly and check that a harmless Personal test appointment appears on both. The license proves access to Ultimate. The recovery key unlocks your calendar. They have different jobs. The service currently links one calendar account to an Ultimate license; creating a new username is not the way to add another device. There is no email password reset that can reconstruct a lost calendar recovery key. If one device still has access, export your plans before clearing it. Support can investigate entitlement problems, but cannot recreate a key the server never held. Use a separate family invitation for your partner. Sharing your own account recovery key gives access to your personal account, not just the family category. 5. Install on your own SparkBox 1. Update SparkBox to 1.6.689 or later using its normal update controls. 2. Go to Apps → TomSparkCal → Install. 3. Wait for the container to become healthy. First installation downloads the image. 4. Choose Access on the app card and configure an HTTPS address. 5. Choose Open. In the calendar, select Your own SparkBox under Where your calendar lives if it is not already selected. 6. Use this calendar address on every family device. The calendar's address is different from your SparkBox dashboard address. You do not need to build Docker images or paste an API key for this setup. The public image starts with empty storage and no Tom Spark personal data or credentials. For access, private Tailscale is a good fit when every household device can join your private network. Enable Tailscale in SparkBox, connect the devices, and use the HTTPS address supplied by the Access picker, including its port when one is shown. An invited calendar user also needs network access to that private address. A public HTTPS domain makes invitations easier for people using ordinary browsers. Follow the Access picker for DNS, certificates and routing. A certificate alone does not prove the network reaches your box. Test the address from the actual phone connection you plan to use. Where your SparkBox offers Cloudflare Tunnel, follow its displayed target; do not guess a different application's port. The module's ordinary host port is loopback-only. Do not expose that raw HTTP port as a substitute for HTTPS. Use SparkBox's existing Access controls so the reverse proxy and calendar agree about the public origin. 6. Share with your partner or family On the first connected device, open Settings → Shared calendar and choose Create a family calendar. Add a harmless appointment to Together and allow it to sync. Then choose Copy invite link or Share family invite and send the link privately. On the other device, open that invitation or paste it into Join shared calendar. Check that the Together appointment appears. Add a second Together test plan from the other device and confirm it returns to the first. That tests both directions instead of assuming a copied link means sharing works. Anyone holding the family link can read and edit that shared calendar. The link contains its encryption key. Do not post it in a public Demox thread, a screenshot, or the website address field of a public profile. Joining adds that device's existing Together events to the family calendar. Review those before joining if you previously used Together for private experiments. Personal and Work are not shared with the family through this link. In hosted account mode, those categories can still sync to your own devices through your personal account. Disconnect this device removes its local connection; it does not revoke a link other people already possess. If an invitation escapes, arrange a new family calendar with a new invitation and move the plans you want to keep sharing. Do not assume deleting a message containing the old link invalidates it. 7. Use it on a phone today On iPhone, open the calendar's HTTPS address in Safari, use Share → Add to Home Screen, and open the new icon. On Android, open it in your browser and use its Install app or Add to Home Screen option where available. This gives quick access and a phone-friendly monthly view. It is still the browser app. It does not make TomSparkCal an iPhone system Calendar account or add the native iOS capture extension and notifications. For a text message today: copy the appointment text, open TomSparkCal, choose Paste a plan or paste into the plan box, preview, and save. If clipboard permission is blocked, touch and hold in the text field and choose Paste. For voice input, your keyboard microphone can dictate into the same field. Browser or keyboard dictation may use the operating system's speech provider; local date parsing does not guarantee local speech transcription. 8. Native iPhone setup when the mobile build is available The iOS build can connect directly to your SparkBox HTTPS origin. In Settings → Where your calendar lives → Your own SparkBox, enter only the HTTPS origin, including its port if needed, without a path, username or invitation fragment. Then join your separate family invitation. For a quick Messages workflow, create an Apple Shortcut with Get Clipboard followed by TomSparkCal's Preview a plan from text action, using Clipboard as the Message. Name it Add to calendar. Add it to the Home Screen or assign it to the Action Button on a supported phone. For spoken capture, use Dictate Text instead of Get Clipboard. For a Share Sheet shortcut, pass Shortcut Input. Confirm the preview before saving. If those actions are absent, check that the native build is installed and has been opened. A Safari Home Screen icon alone cannot register native Shortcuts actions. Older testing builds may retain the earlier app name Still in some system labels. 9. Import Apple, Google or Outlook plans In the browser, export an iCalendar .ics file from the original calendar provider, then open TomSparkCal Settings → Import calendar. Choose the destination category, select the file, review the events, and save. The import limit is 2 MB. Recurring events are expanded through the next two years. An import is a snapshot. Editing Google Calendar tomorrow does not update yesterday's imported file. Avoid repeatedly importing the same calendar without checking for duplicates. Keep the original export until you confirm the result. In the native iOS build, Connected calendars uses calendars already configured on the phone. Add or enable Google in iPhone Settings → Apps → Calendar → Calendar Accounts, then enable Calendars for that account. Open TomSparkCal's Connected calendars, grant the requested access, and select the calendars you want to see. iCloud and other supported phone accounts use the same mechanism. Choose a writable connected calendar in Save to when you want a new appointment owned by that external calendar. Existing external appointments use Apple's editor for editing or deletion. Provider synchronization is performed by iOS and the provider. The browser does not provide a separate Google sign-in connector, and the app does not register itself as an iOS system Calendar account merely because it can read those calendars. 10. Notifications: what works where The public browser package does not include calendar web push. The native iOS build has local event reminders and a Send a test reminder action. Enable reminders, schedule the test, lock the phone, and check the actual alert. Focus, notification permissions and notification settings affect delivery. The iOS app schedules the next 60 local reminders; reopen it to refresh changed family plans and the upcoming schedule. A local reminder for an already downloaded appointment is different from a push alert that someone changed a shared calendar. Family change notifications need an Apple APNs service configured by the host and device registration. They are not enabled just by installing the Docker module. If the app says the Apple push service needs configuration, calendar sync can still work while the app is open. Do not use an untested alert setup for appointments where a missed notification would be costly. 11. Backups, moving devices and changing hosting Settings → Export all events downloads a portable .ics calendar. Keep it privately: it contains readable appointment information. Calendar export preserves appointments; it is not a backup of your account recovery key or family invitation. Save those separately. Before changing browsers, clearing data or moving to another server, export from the device with the complete plans. Browser storage does not automatically move between website addresses. Open the destination, choose its hosting mode, import the file, and review before joining family sharing. Keep the old copy until both the imported plans and sharing have been checked. On SparkBox, encrypted shared records live under ${SBROOT}/modules/tomsparkcal/config/data. Include that directory in your module backups. Updates and container replacement keep it; deleting the data directory does not. A server backup without the family key is not enough to decrypt the appointments. Deleting a hosted account removes that account's backup and releases its license claim. Shared family rooms can remain accessible to people with their invitation. Account deletion and removing family access are separate tasks. 12. Troubleshooting and getting help - Plans appear on one device only: compare the hosting option and exact server address, then confirm that both joined the same family invitation. For self-hosting, make sure the plan is in Together. - Hosted personal plans do not appear: sign in with the same username and recovery key, keep both apps open, and read the account sync status. A family invitation alone does not sync Personal and Work. - HTTPS works on home Wi-Fi but not outside: test domain routing, tunnel access or Tailscale membership. Calendar keys cannot fix a network connection. - Wrong shared-calendar key: use the complete private invitation. Do not create a fresh family on each device and expect them to be the same room. - Haiku unavailable: local parsing remains available. The public module does not carry a funded AI key; the household owner configures optional AI separately. - No reminder: first check whether this is the native iOS build, then permission, Focus and the ten-second test. Browser installation is not native notification setup. - Storage warning: keep the app open and export before clearing anything. Reinstalling is not a recovery method for unsaved local data. For help, post your app/build version, browser or phone type, hosting option, redacted error and the smallest example that reproduces the problem in d/tomsparkcal. Keep real appointments, license keys, recovery keys and invitation links out of public posts. Use a private support ticket for purchase verification. --- Updated September 14, 2026. Website guide. Please keep keys and personal data out of public replies.