User Manual
A desktop wellness app that watches your posture through your webcam and nudges you to sit straight, rest your eyes, drink water, and check in with your mood — all processed locally on your own machine. This guide walks through every screen and feature.
1. System requirements
Operating System
| OS | Minimum version | Architecture |
|---|---|---|
| Windows | Windows 10 or 11 | x64, arm64 |
| macOS | 11 (Big Sur) or newer | arm64 (Apple Silicon); x64 if an Intel build is published |
| Linux | Any modern glibc-based distro | x64 (AppImage is portable across distros; .deb needs a Debian/Ubuntu-family distro) |
Electron 33 is the underlying runtime baseline, which sets the macOS 11 floor above.
Hardware
| Resource | Requirement |
|---|---|
| RAM | 4 GB minimum (Electron + Chromium + MediaPipe WASM pose model all run in-process) |
| Disk space | ~175 MB for the installer download; ~475 MB once installed (includes ~25 MB of bundled ML models/WASM runtime for fully offline posture/face detection) |
| CPU | Any x64 or arm64 CPU from the last ~8 years; posture detection runs the MediaPipe pose model every second, not every frame, so it's not GPU-dependent |
| Camera | Any UVC-compatible USB or built-in webcam — only required for posture monitoring. Eye-break, water, and mood reminders work with no camera at all |
| Display | Any resolution; the app runs as a normal resizable desktop window plus small on-screen reminder overlays |
Software / runtime
None. The packaged installer bundles Node.js, Electron's Chromium runtime, and the compiled better-sqlite3 native module for that OS/architecture — nothing else needs to be pre-installed on the end user's machine.
Network
Not required for core functionality — posture and face detection (the MediaPipe pose model, face-detection model, and WASM runtime) are bundled inside the installer and run fully offline from the first launch, no CDN fetch involved. The only thing that touches the network is auto-update (checks GitHub Releases on startup; silently no-ops if offline). No analytics or telemetry calls are made by the app itself, and camera frames are processed in-memory only — never uploaded.
Permissions
| Platform | What's needed |
|---|---|
| Windows | None beyond running the installer; camera access is granted via the standard Windows camera-privacy prompt |
| macOS | Camera permission (System Settings → Privacy & Security → Camera). Gatekeeper may warn on first launch of a non-notarized build |
| Linux | User must be in the video group for camera access; Wayland additionally needs PipeWire/portals configured |
2. Installation
Installers are published on the GitHub Releases page.
| Platform | File |
|---|---|
| Windows | SitStraight-<version>-win-<arch>.exe |
| macOS | SitStraight-<version>-mac-<arch>.dmg |
| Linux | SitStraight-<version>-linux-<arch>.AppImage or .deb |
Windows
- Download
SitStraight-<version>-win-x64.exe(or-win-arm64.exeon an ARM device). - Double-click it. You'll likely see a blue "Windows protected your PC" SmartScreen warning — this just means the installer isn't yet signed with a paid code-signing certificate, not that anything is wrong. Click "More info", then "Run anyway" to continue.
- This is an NSIS installer (not one-click), so it walks you through a short wizard and lets you choose the install directory (defaults to
%LOCALAPPDATA%\Programs\SitStraight\). - Finish the wizard — SitStraight launches and adds a Start Menu shortcut.
- On first launch, allow the camera permission prompt if you want posture monitoring (eye/water/mood reminders work without it).
Silent install (scripted/unattended): "SitStraight-<version>-win-x64.exe" /S
Uninstall: Settings → Apps → SitStraight → Uninstall, or the uninstaller in the install directory.
macOS
- Download
SitStraight-<version>-mac-arm64.dmg(Apple Silicon) — check the release notes if an x64 build is also published for Intel Macs. - Double-click the
.dmgto mount it, then drag SitStraight into Applications. - Launch from Applications or Spotlight.
- Gatekeeper note: unless the build is notarized with an Apple Developer ID, macOS may warn "unidentified developer" or say the app "is damaged" on first launch (newer macOS shows the "damaged" wording for the same underlying unsigned-app situation). Right-click → Open instead of double-clicking to bypass it; if that still fails, clear the quarantine flag in Terminal:
xattr -cr /Applications/SitStraight.app. See the Troubleshooting section below for the full walkthrough. - Grant the camera permission prompt on first launch. If denied by accident, re-enable under System Settings → Privacy & Security → Camera → SitStraight.
Uninstall: drag SitStraight from Applications to the Trash.
Linux
AppImage (works on most distros, no install step):
chmod +x SitStraight-<version>-linux-x86_64.AppImage
./SitStraight-<version>-linux-x86_64.AppImageSelf-contained — optionally move it to ~/Applications/ and make a .desktop launcher.
.deb (Debian/Ubuntu-family):
sudo dpkg -i SitStraight-<version>-linux-amd64.deb
sudo apt-get install -f # resolves any missing dependenciesLaunch from your application menu, or run sitstraight. Uninstall with sudo apt-get remove sitstraight.
Camera access: managed by your desktop environment, not the app. If the camera doesn't show up, confirm you're in the video group (groups $USER, then sudo usermod -aG video $USER and log out/in). Wayland additionally needs PipeWire/portals configured.
App data location
Not carried over automatically between machines — to migrate your history/settings, manually copy sit-straight.db and settings.json:
| Platform | Path |
|---|---|
| Windows | %APPDATA%\SitStraight |
| macOS | ~/Library/Application Support/SitStraight |
| Linux | ~/.config/SitStraight |
3. First launch
- Sign in (if account sign-in is enabled for your build) — email/password or Google. A restored session on a later launch skips straight past this.
- License/payment (if enabled) — free for everyone through Dec 31, 2026, no purchase needed; a one-time payment unlocks lifetime access after that. The app checks this once per launch and remembers it offline if the license server can't be reached.
- Calibration — a first-time install always starts here, since every posture threshold in the app is measured against your body, not a universal angle.
4. Calibration
Calibration teaches the app your personal posture range in three quick poses, ~10 readings each, using your live webcam feed with a skeletal overlay so you can see what it's reading:
| Pose | What to do |
|---|---|
| Head | Sit exactly the way you normally work — no adjustments. This becomes your baseline. |
| Slouching | Slump forward the way you do when tired. Marks the "bad" end of your range. |
| Correct Posture | Sit tall, ears over shoulders, shoulders relaxed. Your upright target. |
Your sideways lean (natural head tilt) is also captured during the Head pose — this becomes the reference point for left/right tilt detection later.
Recalibrating: Settings → Camera & calibration → Recalibrate, any time your setup changes (new desk height, new chair, new camera position). Every past calibration is kept in a Calibration history list so you can compare readings over time; recalibrating never affects past History/Reports data, since posture is classified using the calibration active at the time each sample was recorded.
5. Monitoring screen
The main screen. Nothing runs until you press Start Monitoring.
Start / Stop / Pause
- Start Monitoring — begins duty-cycled camera sampling (a short burst about once a minute, camera off in between) and starts all four reminders.
- Stop Monitoring — ends the session, stops all reminders, releases the camera. If left stopped for 10 minutes, you'll get one single popup — "Monitoring is paused" — with a button to jump straight back in.
- Pause Notifications — keeps monitoring running (posture is still tracked and logged for History/Reports) but silences every automatic popup — eye, water, mood, posture, and challenge reminders. Your own scheduled To-Do reminders still come through regardless. Click again ("Resume Notifications") to unmute. The app also does this automatically if it detects your camera is locked by another app (e.g. you're on a video call) — no notifications interrupt you mid-meeting, and it un-pauses itself the moment the camera's free again.
Current posture card
- Face detected / Face not detected — a live status line confirming whether a real face is currently being tracked (a dedicated face-detection model, not just a rough pose-skeleton guess).
- The gauge and pill show one of: Aligned, Forward head tilt, Backward head tilt, Left head tilt, or Right head tilt — distinguishing which direction you've drifted from your calibrated baseline, not just "good vs. bad." Left/right tilt is measured against your own calibrated resting lean, with a 20% allowance above it before it counts as a tilt.
- Baseline shows your calibrated angle for reference.
Stat chips
- Posture score — % of today's samples classified Aligned.
- Alerts today — how many slouch notifications fired (an alert fires only after several bad detections land in a row, not on a single blip).
- Streak — consecutive days with at least 2 hours of aligned posture; today gets a grace period until the day ends.
Reminder cards
Small always-visible cards for Eye break, Water sip, Mood check-in, and Posture, each showing a countdown ring to its next fire.
Today's posture timeline
A 30-minute-bucketed bar showing how aligned you were throughout the day.
6. The four reminders
| Reminder | Default interval | Notes |
|---|---|---|
| Eye break (20-20-20) | Every 20 min | Look at something 20 feet away for 20 seconds — a 20-second countdown ring shows on the popup. |
| Water sip | Every 30/45/60 min (your choice) | A gentle hydration nudge. |
| Mood check-in | Every 30/60/90 min (your choice) | Two ten-second sliders — Energy and Pleasantness — plotted onto a mood quadrant (Excited·Happy / Stressed·Anxious / Calm·Content / Tired·Sad). |
| Posture alert | After N consecutive bad detections | N is configurable 2–20 in Settings (default 5, about one per minute) — so you control how forgiving or strict alerts are. |
All four pause automatically while you're away from your desk (no face detected for 2+ minutes, or the system is idle/locked), and stop entirely the moment you press Stop Monitoring — nothing fires in the background while the app just sits open unmonitored.
Reminder popups
A small always-on-top window appears bottom-right with a title, description, and two buttons (varies per kind: Done/Skip, Snooze 5–10 min, etc.). Each kind has its own accent color, emoji, and a short distinct chime. Notification style is configurable in Settings: Banner (in-app overlay, default), Alert (native OS notification + overlay), or Silent (logged, no popup).
7. History screen
Pick any past date to see that day's full breakdown:
- Posture score, good/bad posture time, alerts, longest good streak
- Session breakdown — every individual Start→Stop run that day, with its time range, duration, posture score, slouch/tilt counts, and how many bursts found no face.
- Longest session and first/last session times for the day.
- Eye/water grids — a dot per reminder interval, filled if you acted on it.
- Mood entries logged that day.
- Timeline — the same 30-min aligned-ratio bar as Monitoring, for that day.
8. Reports screen
A weekly rollup, one week at a time (use the ‹ › arrows to move between weeks; you can't go past the current week):
- An overall "you improved/dipped X% this week" banner, weighted across posture, eye breaks, hydration, and mood consistency, versus the previous week.
- Four parameter cards (Posture, Eye breaks, Water, Mood) each with a 7-day bar chart and the trend vs. last week.
- A Monitoring summary — total monitored time, good/slouch/tilt counts, no-face count, detection rate, longest session, and best posture day.
- A day-by-day table — click any row to jump straight to that day in History.
- A Challenges section showing every challenge you've ever accepted and its progress that week.
9. Challenges
Four built-in challenges (Posture Improvement, Back Pain Relief, No Dopamine Challenge, Stand-up Breaks) plus any custom ones you create. All challenges start "Not Started" by default — nothing tracks progress or reminds you until you explicitly press Start Challenge.
- Start → begins tracking, status becomes "Active".
- Mark today done → ticks today off toward your target-day count.
- Stop → pauses it ("Stopped"); Start again later resumes with progress intact, or Restart wipes progress and starts over.
- Reminder frequency per challenge: every 30 min / hourly / every 2 hours / daily — pauses for the rest of the day once you've marked today done.
10. To-Do & reminders
Personal task alarms, separate from the four automatic wellness reminders.
- Add a task: title, optional description, a date (defaults to today, can't be set in the past), a time, and a recurrence — One-time, Hourly, Daily, or Weekdays.
- A one-time task won't fire before its scheduled date; if you miss it (app wasn't open), it still fires once you're back, rather than silently dropping it.
- History — every completed task is logged permanently (even if you later uncheck it, the history entry stays), showing what, when it was due, and the date/time it was actually completed.
- To-Do reminders are the one kind that's never silenced by "Pause Notifications" or camera-busy detection — they're reminders you set yourself, not automatic wellness nudges.
11. Exercise — guided breathing
Five breathing patterns, each with a benefit and best-time-to-use note:
| Exercise | Pattern | Best for |
|---|---|---|
| Box Breathing | 4 in · 4 hold · 4 out · 2 rest | Staying calm under pressure |
| 4-7-8 Breathing | 4 in · 7 hold · 8 out | Winding down / before sleep |
| Equal Breathing | 5 in · 5 out | A steady, beginner-friendly default |
| Energizing Breath | 3 in · 3 out · brief pauses | Mid-day slumps |
| Extended Exhale | 3 in · 6 out | Anxiety, tension, overwhelm |
Pick one to start a guided session with an on-screen breathing rhythm.
12. Settings
Reminders
- Posture alerts: on/off, sensitivity (Low/Medium/High — how close to baseline counts as drifting), and Notify after — a 2–20 slider for how many consecutive bad detections trigger a popup.
- Eye break: on/off (interval fixed at 20 min).
- Water sip: on/off, interval (30/45/60 min).
- Mood check-in: on/off, interval (30/60/90 min).
Camera & calibration
- Current baseline angle, Recalibrate, camera source (if you have more than one), and full Calibration history.
Account & subscription
- Signed-in email, plan, renewal info, Manage subscription, Sign out.
App
- Launch at login — set up automatically during installation; the toggle here just lets you turn it off.
- Notification style — Banner / Alert / Silent.
- Theme — Light or System (Dark is planned).
- Preview notifications — fire any popup kind on demand to see how it looks, without waiting for the real timer.
- Remove history data — permanently deletes posture, mood, and session history to free up disk space. Requires checking two acknowledgements and typing "DELETE" to confirm. Calibration, challenges, and to-dos are never affected.
About
- Version info, website/contact links, and Check for updates.
13. Auto-updates
The app checks GitHub Releases for a newer version on startup and via Settings → About → Check for updates. Updates download in the background; you're prompted to restart once ready. Fully offline-safe — if there's no connection, it just silently does nothing.
14. Privacy
- Camera video is never recorded, saved, or transmitted anywhere — only derived numeric angles ever leave the local pose-detection pipeline.
- Posture and face detection work fully offline — the ML models run entirely on-device; no data about your posture or camera ever needs the internet.
- All wellness data (posture samples, history, mood, challenges, to-dos) lives in a local SQLite database on your machine.
- The only things that ever touch the network are: sign-in/license checks (if enabled), and auto-update checks — both optional and harmless if offline.
See the full Privacy Policy for details on account/license data.
15. Troubleshooting
"Windows protected your PC" / unknown publisher warning (Windows)
SmartScreen flags the installer because it isn't signed with a paid code-signing certificate yet — it's a warning about signing, not a sign anything is actually wrong with the file. To proceed:
- On the blue warning screen, click "More info".
- Click "Run anyway".
This only appears once per downloaded file, not on every launch.
"SitStraight is damaged and can't be opened. You should move it to the Bin" (macOS)
Same underlying cause as the Windows warning above — the app isn't notarized with a paid Apple Developer ID — but modern macOS shows this more alarming "damaged" wording instead of a bypassable prompt. The app is not actually corrupted. Fix it from Terminal:
- Open Terminal (
Cmd + Space→ typeTerminal→ Enter). - Run:
(adjust the path if you installed it somewhere other thanxattr -cr /Applications/SitStraight.app/Applications) - Open the app normally —
open /Applications/SitStraight.app, or just double-click it in Finder.
You only need to do this once per install — not on every launch, and not again after future auto-updates to the same install.
Other common issues
- "Face not detected" while I'm clearly at my desk — check lighting and that your face/shoulders are in frame; extreme side angles to the camera can occasionally read as no-face, since the face model is tuned for front-facing views.
- No notifications during a call — expected: the app detects when another app has locked the camera and automatically holds off until it's free. Check "Pause Notifications" isn't also manually on if you expect them back right after your call ends but they don't return.
- Posture thresholds feel off — recalibrate (Settings → Camera & calibration → Recalibrate); your desk setup or sitting habits may have changed since you first set it up.
16. Getting help
- Website: sitstraight.in
- Contact: info@sitstraight.in