Agora Flat: the open source classroom client that ships as both an Electron app and a web app

What Agora Flat's client actually covers, and what it leaves to flat-server

Agora Flat is an online classroom product, and this repository is its client. The README describes the scope precisely: Web, Windows and macOS. The feature list is the classroom surface you would expect: a multifunctional interactive whiteboard, real-time video and audio chat over RTC, real-time messaging over RTM, screen sharing, and cloud storage for multimedia courseware. Classroom management covers joining, creating and scheduling rooms, including periodic rooms. Recording and replay are split three ways: whiteboard replay, cloud recording for video and audio, and messaging replay.

The audience is narrower than the feature list suggests. This is for people building or customizing a virtual classroom front end, not for someone who wants a hosted teaching tool by Friday. The README points at flat-server, flat-android and the Flat website homepage as separate projects, so the client is one piece of a multi-repository system. Login via GitHub and WeChat is implemented in the client, which tells you it expects to talk to a backend that handles identity.

One thing worth reading twice is the disclaimer. Commercial use is permitted, but the README states that customization requirements and deployment support are not accepted, and that there is no customer support for commercial usage. If you need that, the README directs you to Agora's Flexible Classroom product instead. That is an unusually direct boundary, and it should shape how you plan.

Two clients, one codebase: how the Electron and web builds diverge

The repository is a pnpm monorepo. The root package.json names it flat-monorepo and pins the package manager to [email protected], with a preinstall hook that runs only-allow pnpm. That hook matters: if you reach for npm or yarn out of habit, the install will stop you rather than produce a subtly different dependency tree.

The two clients are separate workspace projects. desktop is the Electron implementation, web is the web implementation, and the README also lists packages and service-providers at the top level, along with a shared flat-components package that the storybook script targets. UI and business logic are separated, which is why Storybook exists as a first-class script: you can develop and inspect components without launching a classroom.

Region handling is baked into the scripts rather than left to runtime configuration. start:cn and start:sg set FLAT_REGION to CN or SG through cross-env before launching, and the packaging scripts ship:cn:all and ship:sg:all do the same for builds. The deployment scripts pub:cn and pub:sg upload to Ali OSS. So the same source produces region-specific artifacts, and the region is a build-time decision, not something you toggle after packaging. The README does not explain what differs between the two regions beyond the endpoints implied by those names.

Installing Agora Flat and running the Electron client for the first time

The README gives a quickstart that does not require a server, which is the fastest way to see whether the client is worth your time. The only prerequisite called out is pnpm; if you do not have it, the README suggests installing it globally with npm.

npm i -g pnpm

Clone or fork the project, then run the install at the repository root. The pnpm workspace file and lockfile live there, so installing from a subdirectory is not what the README describes.

pnpm i

To build and run the Electron client, one command at the root is enough. It goes through scripts/launch/index.js and starts the desktop app on your current system.

pnpm start

Packaging uses the ship scripts. Running pnpm ship packages based on the current system, while pnpm ship:mac and pnpm ship:win target a specific one. The README does not document cross-compiling caveats, so treat the platform-specific scripts as the intended route for a given target.

Running the web client and reading the UI in Storybook

The web client has its own entry point. From the repository root, pnpm start:web delegates to the flat-web package. The README gives an equivalent that makes the delegation explicit, which is useful when you want to work inside that package directly.

cd ./web/flat-web/ && pnpm start

Because UI and business logic are separated, components can be viewed in isolation. The README points to a hosted Storybook address and to a local script, and the root package.json routes that script to flat-components.

pnpm storybook

This is the part of the repository that is easiest to evaluate without any backend at all: if you are considering Agora Flat as a source of whiteboard or classroom UI patterns, Storybook is where to look first. Note the trade-off, though. A component gallery tells you what the pieces look like; it does not tell you whether the RTC and RTM integration behaves the way you need, and the README does not describe a way to exercise those paths without the server side.

Where Agora Flat is the wrong choice

The biggest limitation is structural. This repository is the client. The README lists Flat Server as a related project on GitHub, which means a self-hosted classroom needs at least two repositories wired together, plus whatever identity provider backs the GitHub and WeChat login options. If you were hoping for a single clone-and-deploy artifact, this is not it.

Support expectations are the second constraint, and the project states them itself. The disclaimer says customization requirements and deployment support are not accepted and that no customer support is offered for commercial usage. For a team that needs an SLA or vendor help with a rollout, that is a disqualifier rather than a risk to manage.

Release cadence is the third thing to weigh. The most recent release listed is v2.3.6 from 2025-01-20, preceded by v2.3.5 in September 2024 and v2.3.4 in June 2024. The repository has been pushed to more recently than the last release, so development activity and release activity are not the same signal here. If your adoption plan depends on tagged, packaged versions rather than the main branch, plan around a cadence measured in months.

Finally, the README does not document rollback, upgrade paths between versions, or what changes between regions. Those gaps are not fatal, but they are the questions you will have to answer from the code and from docs/releases rather than from the README.

How Agora Flat differs from the Android client and from Agora's commercial classroom

Two real alternatives sit on either side of this repository, and they differ in kind rather than degree.

flat-android is the Android client from the same organization. The difference is reach, not approach: it covers a platform this repository does not, since the README scopes this client to Web, Windows and macOS. If your students are on tablets, the client you want is in a different repository, and the two clients presumably share the server rather than the code.

Agora's Flexible Classroom is the commercial product the README itself points to when it declines customization and deployment support. The difference in approach is who carries the operational burden. With Agora Flat you get MIT-licensed client source and you assemble the system, including the server repository and region configuration. With Flexible Classroom you are buying the hosted arrangement the disclaimer steers commercial requirements toward. The README does not compare features between the two, so treat that link as a routing decision, not a feature matrix.

If what you actually want is a whiteboard rather than a classroom, note that this repository bundles whiteboard, RTC, RTM, recording and classroom management together. There is no documented way in the README to take only the whiteboard layer.

Licence, upgrade cost and what maintenance looks like from the outside

The repository is MIT licensed, and the root package.json carries "license": "MIT". The README's licence section adds a copyright line for Agora Corporation and a note that use of the Flat or GitHub logos must follow GitHub's logo guidelines. MIT is permissive, but the disclaimer about commercial customization and support is a separate statement from the licence, and it is the one that affects what you can expect from the maintainers rather than what you may legally do with the code. This article is not legal advice; read the LICENSE file and the disclaimer together before a commercial rollout.

Upgrade cost is shaped by the monorepo. The package manager is pinned to [email protected] with an only-allow pnpm preinstall guard, so dependency changes ripple through a workspace that includes desktop, web, packages and service-providers. The environment variable reference under docs/env is the place the README points for configuration, and docs/releases is where version descriptions live. Neither is summarized in the README, so a version bump means reading those directories rather than a changelog paragraph.

The last push to the repository was on 2026-09-10, and the latest tagged release is v2.3.6 from 2025-01-20. Those two dates describe different things, and anyone evaluating whether to track main should look at both rather than assuming releases and commits move together.

Editorial conclusion

Adopt Agora Flat if you want a working virtual classroom front end in TypeScript and are willing to run the separate flat-server alongside it, or if you only need to read and modify the UI. Do not adopt it if you expect the repository to contain a deployable backend or commercial deployment support: the README states plainly that customization requests and deployment support are not accepted. Before committing, verify which region your build targets, since the FLAT_REGION environment variable and the start:cn and start:sg scripts package different endpoints, and check the environment variable reference under docs/env for the keys your deployment needs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. netless-io/flat on GitHub
4. README
5. Releases