GitHub - BandarLabs/Cobalt: An SDK for building real apps for your Kobo eInk reader

Apps and an SDK for Kobo e-readers.

Cobalt is an open-source application platform for Kobo. It provides a launcher, an App Store, a Rust SDK, a runtime with capability isolation, and a Clara BW simulator.

After one USB installation, users can install, update, and remove signed apps over Wi-Fi. App releases are independent from Cobalt platform releases, so a new app can appear in Store without reinstalling or updating Cobalt.

_{Recorded on a Kobo Clara BW at 3× speed: apps, Store discovery, and the complete Sudoku install lifecycle.}

Features

• Signed Wi-Fi app installation, updates, and removal
• Separate Settings-based updates for the Cobalt platform
• Apps run as separate unprivileged processes
• Per-app capability checks for network, storage, audio, frontlight, and other device services
• Declarative e-ink UI toolkit and browser simulator
• Full and partial refresh planning for the 1072 x 1448 Clara BW panel
• Static ARMv7 binaries with no device-side package manager
• Recovery-safe app and catalog transactions

Every screenshot below is a real capture from a Kobo Clara BW. Store manages the installable applications; Settings and Terminal remain protected system utilities.

Launcher Opens installed apps and always keeps a route back to the Kobo reader.	App Store Browses signed apps and installs, updates, removes, and reinstalls them over Wi-Fi.	Sudoku A Store-only touch game that also proves delivery of an app absent from the platform package.
Audiobook Studio Researches, writes, narrates, and plays an original audiobook.	Gutenbird Reads any OPDS library: Project Gutenberg, Standard Ebooks, Open Library, or one you add.	Hacker News Top, New, Ask, and Show stories with complete comment threads.
Feeds Discovers a site's feed and presents its articles without the browser layout.	Daily Brief Collects the day's stories while the reader is using another app.	AI Command Center Asks a question and turns the answer into touch-friendly reading.
Sidekick Lets a reader approve or deny requests from coding agents.	Terminal A panel-native shell with keys that send input immediately.	Components Shows the UI toolkit's controls, layouts, typography, and states.
Settings Manages connectivity and hardware, and keeps platform updates separate from Store.	Todo A persistent list with touch entry and completed-item states.	Tic-tac-toe A two-player touch game using partial refreshes for individual cells.
arXiv Reader Browses and searches preprints, keeps them for offline reading, and sets their mathematics as type.	Morse Sends a typed message on the front light, a letter at a time, drawn across the panel as it goes.
Magnet Locates the hall sensor behind the bezel and reports its changes.

Install

Install Rust, add the ARM target and connect a charged Clara BW over USB:

git clone https://github.com/BandarLabs/Cobalt.git
cd Cobalt
rustup target add armv7-unknown-linux-musleabihf
cargo run -p kobo-cli -- setup

Restart the reader and open Cobalt from Kobo's menu. Future applications are installed from Store over Wi-Fi. Full Cobalt updates remain under Settings.

Readers running Cobalt 0.1.x need the 0.2.0 platform update once to add Store. After that update, new and updated apps arrive independently through the app catalog.

See docs/INSTALL.md for the complete walkthrough and recovery steps.

App Store

Store reads a signed catalog from the fixed app-catalog GitHub release. Each package contains one ARM executable and a signed canonical manifest. The runtime verifies the catalog, package, installed manifest, and binary before launch.

Store is the only app-management surface. The applications bundled with the first 0.2.0 platform install appear as installed, can be removed and reinstalled in the same session, and can be updated in place without creating a second launcher entry. Platform utilities such as Settings and Terminal are shown as installed system apps and cannot be removed.

Apps are published automatically when an app PR is merged into main. Publishing an app does not require changing the Cobalt version or creating a platform release.

Sudoku remains Store-only and is intentionally absent from the USB platform package, so installing it verifies delivery of an app that was not already on the reader.

Build an app

cargo install --path crates/kobo-cli
kobo new my-app
cd my-app
kobo dev

kobo dev runs the app in the Clara BW browser simulator. Start with the SDK documentation; the repository also keeps the deep implementation guide.

What the SDK provides

Apps request services through the SDK instead of opening device resources directly. The runtime can deny a request because it was not declared, is too expensive for the current battery state, or is unsupported, and each refusal is returned to the app as a value it can present or recover from.

See the SDK docs for the application model, UI components, runtime services, capabilities, developer-facing crates, and the CLI command reference.

Contributing apps

App contributions are regular pull requests:

1. Add the app as a workspace package under apps/<app-id>/.
2. Add its release metadata to apps/catalog.json.
3. Add unit and Clara BW layout tests.
4. Run the app in the browser and runtime simulators.
5. Open a pull request.

After the PR is reviewed and merged, the Publish apps workflow builds every registered app for ARM, signs the packages and catalog, and updates the fixed Store channel. App versions are independent from the Cobalt platform version.

See docs/CONTRIBUTING_APPS.md for metadata, capabilities, testing, and release details.

Repository layout

Development

cargo test --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all --check
cargo run -p kobo-cli -- run --sim --app sudoku

Additional guides:

• Developing Cobalt
• Working with devices
• Publishing apps
• Porting to another Kobo
• Security policy

Safety and support

Cobalt does not replace Kobo's boot chain. Device support is explicitly gated by hardware and firmware identity, and a reboot returns to the stock reader. The first installation still modifies files on the user storage partition and is provided without warranty.

Only the Clara BW profile has been tested. Do not install Cobalt on another model until that model has a reviewed and hardware-tested profile.

License

GNU Affero General Public License v3.0. See LICENSE and THIRD-PARTY.md.