SubDeskOS

Substitute desk management OS for K-12 districts. Real coverage, real compliance, zero excuses.

---

What is SubDeskOS

SubDeskOS is the backend operating layer for substitute teacher dispatch, scheduling, and credentialing across 589 school districts (up from 412 — took us long enough, I know). It handles the full lifecycle: absence notification → sub match → dispatch → confirmation → payroll handoff.

Now with real-time biometric verification at check-in kiosks. Still not sure this was a good idea but the Fresno Unified pilot said they wanted it and honestly the fingerprint matching latency is actually fine. Priya got it under 800ms on the Pi 4 units.

---

What's New (v2.9.x)

Biometric Verification at Check-In

Starting v2.9.0, kiosks running SubDeskOS firmware ≥2.9 support real-time fingerprint + optional face-liveness verification before a sub is marked "arrived." This uses our internal bioverify module — not a third-party SDK, we wrote it ourselves after the vendor licensing fell apart in March. It works. Mostly.

• Fingerprint matching via ISO/IEC 19794-2 template format
• Face liveness check (passive, no blinking-at-camera nonsense)
• Configurable fallback to PIN if biometric hardware unavailable
• All biometric data processed on-device — nothing hits the cloud. This was non-negotiable for FERPA.

To enable:

biometric:
  enabled: true
  mode: fingerprint+liveness   # or just "fingerprint" if the camera is broken again
  fallback: pin
  liveness_threshold: 0.87     # don't go below 0.80, learned this the hard way

---

FERPA-Compliant Dispatch Tier

The new FERPA Dispatch Tier (badge above) enforces:

• All PII fields encrypted at rest (AES-256-GCM, keys in Vault, not hardcoded — yes I fixed that, see git blame)
• Audit log for every record access, immutable, 7-year retention
• Consent-scoped data sharing between district and sub agency
• No sub sees student data. Ever. This was already true but now it's enforced at the API layer too.

Districts enrolled in the FERPA tier get a separate dispatch queue and a compliance report auto-generated every 90 days. Talk to Omar if you need the report format changed; he owns that template.

Enable in district config:

{
  "dispatch_tier": "ferpa",
  "audit_log": {
    "backend": "immutable_s3",
    "retention_days": 2555
  }
}

---

Experimental: SMS Fallback for Rural / No-Internet Schools

Some of our districts are in areas where internet connectivity at the school building is... aspirational. For those cases we now have an experimental SMS-based dispatch fallback.

When the SubDeskOS agent at a school loses connectivity for >90 seconds, it automatically switches to SMS dispatch via a registered short code. Subs get a text, confirm with a reply, and the record syncs when connectivity returns.

How to enable (opt-in only, still experimental):

connectivity:
  sms_fallback:
    enabled: true
    provider: twilio
    short_code: "74683"
    # twilio_sid and auth pulled from env — DO NOT hardcode here again
    offline_queue_ttl: 14400   # 4 hours, after that we give up and call the sub

Supported scenarios:

• Sub confirmation and cancellation via reply SMS
• Emergency absence notification to district coordinator
• Basic check-in acknowledgment (biometric skipped in SMS-fallback mode, obviously)

Not supported yet:

• Two-way scheduling changes via SMS (next quarter maybe, no promises)
• MMS (nobody asked for this)
• International numbers (¿por qué alguien lo necesitaría? but filed as SD-933 anyway)

⚠️ SMS fallback is experimental. Don't turn it on for large urban districts. It is explicitly designed for low-volume rural schools (<30 subs in rotation). You have been warned. I have put this warning in three places.

---

District Coverage

SubDeskOS currently serves 589 districts across 31 states. Full coverage map at subdesk.io/coverage.

Previously 412. The 177 new districts are mostly from the Southeast expansion Kenji's team finished in Q2. A few in the Pacific Northwest are still in onboarding limbo — you'll see them listed as status: pending_data_migration in the admin panel. That's expected.

---

Supported Hardware (Kiosk Mode)

Device	Biometric	SMS Fallback	Notes
SubDeskOS Pi Kit v3	✅	✅	Recommended
SubDeskOS Pi Kit v2	fingerprint only	✅	Upgrade camera module for liveness
Lenovo ThinkCentre Tiny	✅	❌	No onboard modem
Browser kiosk (any)	❌	❌	Use PIN fallback

---

Quick Start

git clone https://github.com/subdesk-os/subdesk-os
cd subdesk-os
cp config/example.yml config/local.yml
# edit local.yml — at minimum set district_id and api_base_url
./scripts/bootstrap.sh

For Docker:

docker compose up -d

Docs at docs.subdesk.io. Somewhat outdated. Working on it.

---

Configuration Reference

See docs/config-reference.md. The biometric config options are documented there as of v2.9.1 — Fatima added them last week.

---

Contributing

PRs welcome. Please run make lint && make test before opening anything. If tests are failing on your branch it's probably the bioverify mock — there's a known issue with the mock clock on Windows (SD-897, no ETA, sorry).

---

License

BSL 1.1. See LICENSE. Commercial use requires a district subscription. Пожалуйста, не пытайтесь обойти это — we will find out.

---

SubDeskOS is not affiliated with any state department of education. FERPA compliance claims refer to our internal data handling practices and have been reviewed by outside counsel as of 2026-Q1.