ClassroomIO

✨ About ClassroomIO

ClassroomIO is an intelligent customer training platform that helps SaaS companies use education to grow their business. Create high-quality learning experiences faster, deliver them across your customer journey, and use AI to scale customer education.

Who It's For

Use Case	What You Can Do
Customer Education	Help customers understand your product, learn key features, complete onboarding, and get more value from your platform.
Partner Training	Train resellers, implementation partners, and distributors on your products, processes, and standards.
Employee Training	Onboard employees, deliver internal training, and manage compliance and certification programs.

Key Features

1. Create

• Build Courses: Create courses faster with AI-powered course creation tools.
• Cohorts: Group learners into organized learning groups and track their progress through training programs.
• Certifications: Issue branded certificates to recognize learners who complete courses or meet training requirements.
• Team Collaboration: Add team members to your academy and work together to manage learners, assign courses, and coordinate training.
• Multiple Languages: Deliver learning experiences in 10+ languages for learners globally.

2. Distribute

• Branded Customer Academies: Launch branded learning academies on custom domains.

• Manage Organizations: Manage multiple organizations and their learning environments.

• Learner Dashboard: Give learners one place to access courses, assignments, and track progress.

• Learning Paths: Guide learners through structured learning experiences.

• Embedded Learning: Embed videos, slides, and documents directly into your courses to give learners a seamless learning experience.

• REST API & Webhooks: Connect ClassroomIO to your existing systems, access learning data, and trigger workflows across your tools.

• Zapier Integration (Coming Soon): Connect ClassroomIO with your favourite tools and automate workflows across your existing apps.

  3. Intelligence

AI Lesson Tutor: Learners get access to an AI assistant that explains concepts, answers questions, and summarizes course material to help them learn with confidence.

MCP Server: Connect ClassroomIO with your favourite AI tools and coding agents to create courses and interact with your learning platform.

AI-Powered Workflows: Use AI integrations to streamline course creation and learning operations.

For what's coming next, see the public roadmap.

Built With

• SvelteKit
• Hono
• PostgreSQL
• Better Auth
• TailwindCSS

Get a Demo

You can book a quick 15 min demo to see if ClassroomIO is a good fit for you

Getting Started

To get a local copy up and running, please follow these simple steps.

Prerequisites

Here is what you need to be able to run ClassroomIO.com

• Node.js (Version: >=20.19.3) — required
• pnpm (v10) — required; the package scripts call pnpm directly, so npm/yarn are not substitutes
• Docker — required; runs Postgres + Redis (no local install of those needed)

Project Structure

This repo is a monorepo that consists of these primary apps:

1. website: The landing page of ClassroomIO hosted here
2. api: The api service that handles PDF, video processing, Emailing and Notifications.
3. dashboard: The web application that runs the learning management system hosted here.
4. docs: Official documentation of ClassroomIO hosted here

The repository also contains shared packages under packages/ (for example packages/db, packages/utils, and packages/ui).

Development

Local Setup

Before you start: make sure pnpm and Docker are installed (see Prerequisites). New to the project? Read DEV_SETUP_NOTES.md first — it's a full step-by-step walkthrough with a troubleshooting reference for the errors you're likely to hit.

1. Fork the repo, then clone it:

   git clone https://github.com/classroomio/classroomio.git
   

2. Go to project folder:

   cd classroomio
   

3. Set up Node (using nvm):

   nvm use
   

   You first might need to install the specific version and then use it:

   nvm install && nvm use
   

   You can install nvm from here.

4. Install dependencies:

   pnpm i
   

5. Set up your .env files:

   Each app reads its own .env. In apps/api, apps/jobs and apps/dashboard, duplicate .env.example to .env and fill the values below (host ports). The secret values are placeholders — generate each one with openssl rand -hex 32 rather than copying the example text. The two PRIVATE_SERVER_KEY values must match — they authenticate the dashboard's server-to-server calls to the API, so generate it once and paste the same value into both files.

   • apps/api/.env:

     DATABASE_URL="postgresql://postgres:postgres@localhost:5432/classroomio"
     REDIS_URL="redis://localhost:6379"
     PUBLIC_SERVER_URL="http://localhost:3002"
     TRUSTED_ORIGINS="http://localhost:5173"        # the dashboard dev origin
     BETTER_AUTH_SECRET="<generate-with-openssl-rand-hex-32>"
     PRIVATE_SERVER_KEY="<generate-with-openssl-rand-hex-32>"   # generate once; use the SAME value in the dashboard
     DASHBOARD_ORIGIN="http://localhost:5173"        # optional; used for invite/email links back to the dashboard
     

   • apps/jobs/.env: The jobs service handles background tasks (emails, media processing, analytics rollups, etc.).

     Recommended setup (simplest):

     cd apps/jobs
     ln -s ../../apps/api/.env .env  
     

   • apps/dashboard/.env:

     PUBLIC_SERVER_URL="http://localhost:3002"
     PRIVATE_SERVER_URL="http://localhost:3002"      # used by the SSR auth proxy — required, or login returns "API upstream not configured"
     PRIVATE_SERVER_KEY="<generate-with-openssl-rand-hex-32>"   # must match the API (paste the value generated above)
     PUBLIC_IS_SELFHOSTED=false
     

• website: pnpm website:dev

• docs: CHOKIDAR_USEPOLLING=true pnpm dev --filter=@cio/docs (Requires Node ≥ 22.12: nvm use 22.12 first. The polling flag prevents an EMFILE error on macOS when other dev servers are already consuming file descriptors.)

  On Windows, nvm (nvm-windows) switches the Node version globally rather than per-shell, so run this from a separate terminal window than the one running api/dashboard — switching versions there won't affect processes already started in other terminals.

  The docs' API reference is built from a static OpenAPI spec fetched at dev-server startup from the deployed production API (apps/docs/scripts/fetch-openapi.mjs), not from your local api. If you're working on public API routes and want to preview unmerged changes in the docs before they're deployed, generate the spec from your local code instead:

  # from apps/api, with local Redis running (same as normal api dev setup)
  OPENAPI_SKIP_CDN_PURGE=1 npx tsx scripts/upload-openapi-spec.ts
  cp dist/openapi/public-api/openapi.json ../docs/openapi/public-api.json
  

  Then start the docs server with pnpm exec blume dev from apps/docs instead of pnpm dev --filter=@cio/docs — the latter re-runs fetch-openapi.mjs as a prestep on every start and will overwrite your local copy with the stale remote spec again.

11. Login into dashboard:

    • Visit http://localhost:5173/login
    • Enter email: [email protected]
    • Enter password: 123456

    To learn more about how to login with a dummy account, go here.

Enabling the AI Course Assistant

The in-course AI chat (course authoring, plan generation, lesson edits) is disabled by default. Enable it by setting at least one provider API key in apps/api/.env (or the root .env for the Docker stack):

# Pick one or more — the dashboard model picker exposes Gemini 2.5 Flash and GPT-4o.
OPENAI_API_KEY=sk-...        # enables GPT-4o
GOOGLE_API_KEY=AIza...       # enables Gemini 2.5 Flash (default model in the picker)
ANTHROPIC_API_KEY=sk-ant-... # supported in code; not currently in the picker UI

Notes:

• The GET /agent/status endpoint flips to enabled: true as soon as any of those keys is set, which is what the dashboard checks before showing the AI button on a course.
• Each chat request sends the user-selected model (persisted in localStorage as classroomio-ai-chat-model). The API resolves the provider for that model (packages/utils/src/agent-models) and returns 503 AI_NOT_CONFIGURED if that provider's key is missing.
• Optional Tinybird observability: set TINYBIRD_TOKEN (and optionally TINYBIRD_BASE_URL) in apps/api/.env. Events are silently skipped when the token is absent.
• More detail on architecture, tools, and routes lives in prd/ai-course-assistant [DONE]/README.md.

Docker Compose (Full Stack)

cp .env.example .env   # copy env template, edit for your domain
./classroomio.sh start           # pulls pre-built images; use --build to build from source

The script reads root .env via docker compose --env-file .env and auto-generates a secure PRIVATE_SERVER_KEY (and BETTER_AUTH_SECRET) when missing. Run ./classroomio.sh with no arguments for the full lifecycle menu (install, start, stop, restart, upgrade, logs, backup).

See .env.example for the full list of environment variables with required/optional grouping, and docker/docs/SELF_HOST.md for the complete Docker self-hosting guide. To raise upload caps (documents, videos, assignment files), set the UPLOAD_MAX_*_MB vars in .env — see the docs.

Publishing

When cutting releases for hosted assets or the npm MCP package, run:

• Storybook — pnpm --filter @cio/storybook storybook:publish
• Course widget embed — pnpm --filter @cio/embeds embeds:publish
• Question type picker — pnpm --filter @cio/embeds embeds:publish (same script builds and uploads both embeds)
• MCP (@classroomio/mcp) — bump the version in packages/mcp/package.json, then pnpm mcp:build and pnpm --filter @classroomio/mcp publish