Capsule Framework

Ship any web bundle inside a generated native shell — with an on-device runtime (CivetWeb + QuickJS), a native-API bridge, and OTA code push (CodeSync).

Monorepo (pnpm + turbo): framework core, CLI, native Android shell, iOS shell (in bring-up), CodeSync delivery server, and the documentation site.

Layout

Path	What
packages/core	the app-facing TypeScript API (camera, filesystem, network, app lifecycle, db, ai, …)
packages/cli	capsule init/add/add-ui/sync/dev/build/run/doctor + OTA (codesync)
packages/capsule-android	the Android native shell (Kotlin + C AAR)
packages/capsule-ios	the iOS shell (Swift package — manifest at the repo root, Package.swift)
packages/native/civetweb	the embedded HTTP server, vendored and shared by both shells
packages/ui-kit	Capsule UI — Tailwind class builders copied into apps by capsule add-ui
packages/codesync-api	self-hostable OTA delivery server (Fastify, AGPL-3.0)
docs/	documentation source (mkdocs) — index inside

Agents: read AGENTS.md — task, target, files, navigation, update rules.

Documentation

The docs site is built with mkdocs (mkdocs gh-deploy in CI):

• Guide — install, quickstart, native APIs (db, ai, push, …), publishing
• Reference — CLI, core API, lockfile
• Concepts — architecture, principles, comparisons, primers
• Decisions — binding ADRs
• Contributing — environment, testing, CI, release, workflows
• Project — roadmap, state, history, business, server design

Exploring locally: mkdocs serve (state at a glance: docs/project/state.md).

Development

Install dependencies, then build and test everything from the root:

pnpm install
pnpm build
pnpm test
pnpm docs:check    # docs consistency check

Per-package commands are in each packages/*/README.md. Machine-level environment setup (JDK, Android SDK, emulators): docs/contributing/environment.md.

Contributing

See CONTRIBUTING.md for setup, the test layers and the pull-request process, and the Code of Conduct. Report security issues privately — see SECURITY.md.

License

Apache-2.0, except packages/codesync-api, which is AGPL-3.0 — self-host it freely; a modified version offered as a hosted service must publish its changes. Third-party notices: NOTICE.