# Capgo: build Capacitor apps with AI, ship updates instantly
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://sonarcloud.io/summary/new_code?id=Cap-go_capgo)
[](https://codspeed.io/Cap-go/capgo?utm_source=badge)
[](https://snyk.io/test/github/Cap-go/capgo)
[](https://github.com/Cap-go/capgo/actions/workflows/bump_version.yml)
[](https://github.com/Cap-go/capgo/actions/workflows/build_and_deploy.yml)
Capgo is the AI-ready platform to build, ship, and maintain Capacitor apps:
Capacitor skills and MCP servers for AI coding agents (Claude Code, Codex,
Cursor, Copilot, Gemini CLI), maintained Capacitor plugins, cloud native
iOS/Android builds with App Store and Google Play publishing, live updates with
channels and rollback, and release monitoring.
This repository is the open-source core of [Capgo](https://capgo.app/): the web
console, the backend API (Cloudflare Workers + Supabase, including the hosted
MCP endpoint), and the `@capgo/cli` workspace (including the local MCP server).
- [Capacitor skills for AI agents](https://capgo.app/skills/)
- [AI agent setup](https://capgo.app/agents/)
- [Capgo MCP docs](https://capgo.app/docs/ai/mcp/)
- [Cloud native builds](https://capgo.app/native-build/)
- [Capacitor plugins](https://capgo.app/plugins/)
- [AI tools for Capacitor](https://capgo.app/best/ai-tools-for-capacitor/)
## Use with AI coding agents
Install the Capgo Capacitor skills in your agent (Claude Code, Codex, Cursor,
Copilot, Gemini CLI):
```bash
npx skills add Cap-go/capgo-skills
```
Connect the Capgo MCP server so the agent can manage apps, channels, bundles,
native builds, and stats:
- Hosted MCP: `https://api.capgo.app/mcp` ([docs](https://capgo.app/docs/ai/mcp/))
- MCP Events on the hosted server: subscribe with `events/subscribe` or `capgo_subscribe_events` for `build.succeeded`, `build.failed`, `bundle.uploaded`, and `bundle.deployed` (Standard Webhooks delivery).
- Local MCP (served by the CLI in this repo): `npx @capgo/cli@latest mcp` (stdio only; event callbacks require the hosted MCP).
Per-agent setup instructions are at [capgo.app/agents](https://capgo.app/agents/).
## Features
- โ๏ธ Cloud / Self hosted Support: Use our [Cloud](https://capgo.app/) to manage
your app updates or yours.
- ๐ฆ Bundle Management: Download, assign to channel, rollback.
- ๐บ Channel Support: Use channels to manage different environments.
- ๐ฏ Set Channel to specific device to do QA or debug one user.
- ๐ Auto Update: Automatically download and set the latest bundle for the app.
- โ
Official Appflow alternative: our Capacitor updater plugin is the official alternative to Ionic Appflow.
- ๐ Rollback: Reset the app to last working bundle if an incompatible bundle
has been set.
- ๐ **Delta Updates**: Make instant updates by only downloading changed files.
- ๐ **Security**: Encrypt and sign each updates with best in class security
standards.
- โ๏ธ **Battle-Tested**: Used in more than 3000 projects.
- ๐ View your deployment statistics
- ๐ Supports Android and iOS
- โก๏ธ Capacitor 8/7/6/5 support
- ๐ **Open Source**: Licensed under GNU AFFERO GENERAL PUBLIC LICENSE
- ๐ **Open Source Backend**: Self install
[our backend](https://github.com/Cap-go/capgo) in your infra
### Security updates
The Capgo console shows **published** Capacitor security advisories and optional email
alerts for your apps. The `security_updates` email preference defaults to off; turn it on
under Account settings, Notifications. Per app, open Observe, Security updates to review
matches against native package versions already reported on bundles. Public docs:
[Notifications security advisories](https://capgo.app/docs/webapp/notifications-security-advisories/),
[Observe security updates](https://capgo.app/docs/webapp/observe-security-updates/),
[website #1413](https://github.com/Cap-go/website/pull/1413),
[Console security updates](https://github.com/Cap-go/website/pull/1394), and
[Security advisories feature](https://github.com/Cap-go/website/pull/1393).
## Usage
Capgo is deployed to production on Cloudflare workers and Supabase.
Cloudflare workers take 99% of the traffic. Supabase is used for internal calls,
for internal tasks such as CRON jobs that call functions.
When self-hosted, installing only Supabase is sufficient.
## Why Cloudflare Workers + Supabase
We support both deployments for practical reasons:
- **Supabase** is the legacy backend and the only required piece for
self-hosting.
- **Cloudflare Workers** runs the same backend code (via the Hono adapter) but is
much cheaper at Capgo scale. With ~50M devices, Supabase Edge Functions are
cost-prohibitive because they follow AWS pricing. Cloudflare is ~10x cheaper
for our traffic profile.
In production, we route most traffic through Cloudflare Workers for cost and
scale, while Supabase remains the reference backend and the default for
self-hosted deployments. Capgo cloud console and current CLI calls go to the
Cloudflare API hosts (`VITE_API_HOST` / `hostApi`). Capgo cloud still publishes
a small Supabase function allowlist for Postgres `pg_net` (`triggers`) and for
legacy CLI compatibility via `/functions/v1` through 2026-10-28. Self-hosted
deployments keep using `/functions/v1`. Plugin hot paths and other unused Capgo
cloud endpoints are not published on Supabase.
## Project structure (self-hosting map)
If you're self-hosting, the key pieces live in a few top-level directories:
- `supabase/` - **Primary backend for self-hosting**
- `supabase/functions/` - Edge functions (Deno) that power the API
- `_backend/` - Core implementation used by both Supabase and Cloudflare
- `public/` - Public API routes used by customers and apps
- `private/` - Internal API routes for the console and ops tooling
- `plugins/` - Plugin endpoints (updates, stats, channel_self, etc.)
- `triggers/` - Database triggers and CRON functions
- `supabase/migrations/` - Database schema and RLS policies
- `supabase/seed.sql` - Local seed data for tests/dev
- `supabase/schemas/prod.sql` - Production schema dump (reference only)
- `cloudflare_workers/` - **Optional** Cloudflare Workers deployment (prod traffic)
- `cloudflare_workers/snippet/` - Geo routing for replicas
- Worker entry points and deploy config live here
- `src/` - Frontend Vue 3 web console (Vite + Tailwind + DaisyUI)
- `src/pages/` - File-based routes
- `src/components/` - Reusable UI components
- `src/services/` - API clients and integrations
- `src/stores/` - Pinia stores
- `sql/` - Raw SQL helpers and maintenance scripts
- `scripts/` - Dev/build scripts used by CI and local tooling
- `tests/` - Backend Vitest tests (run in parallel)
- `playwright/` - Frontend E2E tests
- `docs/` - Extra documentation and guides
- `android/`, `ios/` - Capacitor native projects (mobile builds)
Quick self-hosting path:
1. `supabase/` is enough to run the backend locally.
2. `src/` is the web console you point to your own backend.
3. `cloudflare_workers/` is only needed if you want to run the Workers layer
instead of (or in front of) Supabase.
## Backend endpoints (what lives where)
The backend is split by responsibility to keep routes clear and access scoped:
- `supabase/functions/_backend/public/` - **Public API** exposed to customers.
This is the documented API on the website for customers that want to interact
with Capgo programmatically (apps, channels, bundles, devices, etc.).
- `supabase/functions/_backend/private/` - **Private API** used internally.
The console (web UI) uses this heavily for admin/ops workflows. It is not
publicly accessible. Some UI flows still use the public API where appropriate.
- `supabase/functions/_backend/plugin_runtime/` - **Plugin API** used by the
`@capgo/capacitor-updater` plugin running inside apps:
- `plugins/updates` - device update checks and bundle download flow
- `plugins/stats` - upload usage stats from devices
- `plugins/channel_self` - allow a device to opt into a channel (QA/debug)
- `supabase/functions/_backend/triggers/` - **Triggers & CRON** for automated
backend jobs (queue consumers, scheduled tasks, DB-triggered flows).
When self-hosting, you generally expose `public` + `plugin_runtime` (via the
plugin worker / Deno `updates` ยท `stats` ยท `channel_self` entries). `private`
should stay internal and locked down. `triggers` runs automatically.
## Production schema (prod.sql)
`supabase/schemas/prod.sql` is a schema dump of the production database. It is
generated via `bun run schemas` (or `bun run schemas:local`) and is meant for
reference/diffing, not as a source of truth. All actual schema changes live in
`supabase/migrations/`.
## Documentation
https://github.com/Cap-go/capacitor-updater/wiki/Capgo-Sandbox-App
- [Changing Supabase](supabase/migration_guide.md)
## Plugins
All the following official plugins are already installed and pre-configured:
- [Action Sheet](https://github.com/ionic-team/capacitor-plugins/tree/main/action-sheet) -
Provides access to native Action Sheets.
- [App](https://github.com/ionic-team/capacitor-plugins/tree/main/app) - Handles
high level App state and events.
- [App Launcher](https://github.com/ionic-team/capacitor-plugins/tree/main/app-launcher) -
Allows to check if an app can be opened and open it.
- [Browser](https://github.com/ionic-team/capacitor-plugins/tree/main/browser) -
Provides the ability to open an in-app browser and subscribe to browser
events.
- [Camera](https://github.com/ionic-team/capacitor-plugins/tree/main/camera) -
Provides the ability to take a photo with the camera or choose an existing one
from the photo album.
- [Clipboard](https://github.com/ionic-team/capacitor-plugins/tree/main/clipboard) -
Enables copy and pasting to/from the system clipboard.
- [Device](https://github.com/ionic-team/capacitor-plugins/tree/main/device) -
Exposes internal information about the device, such as the model and operating
system version, along with user information such as unique ids.
- [Dialog](https://github.com/ionic-team/capacitor-plugins/tree/main/dialog) -
Provides methods for triggering native dialog windows for alerts,
confirmations, and input prompts.
- [Filesystem](https://github.com/ionic-team/capacitor-plugins/tree/main/filesystem) -
Provides a NodeJS-like API for working with files on the device.
- [Geolocation](https://github.com/ionic-team/capacitor-plugins/tree/main/geolocation) -
Provides simple methods for getting and tracking the current position of the
device using GPS, along with altitude, heading, and speed information if
available.
- [Haptics](https://github.com/ionic-team/capacitor-plugins/tree/main/haptics) -
Provides physical feedback to the user through touch or vibration.
- [Keyboard](https://github.com/ionic-team/capacitor-plugins/tree/main/keyboard) -
Provides keyboard display and visibility control, along with event tracking
when the keyboard shows and hides.
- [Local Notifications](https://github.com/ionic-team/capacitor-plugins/tree/main/local-notifications) -
Provides a way to schedule device notifications locally (i.e. without a server
sending push notifications).
- [Motion](https://github.com/ionic-team/capacitor-plugins/tree/main/motion) -
Tracks accelerometer and device orientation (compass heading, etc.).
- [Network](https://github.com/ionic-team/capacitor-plugins/tree/main/network) -
Provides network and connectivity information.
- [Push Notifications](https://github.com/ionic-team/capacitor-plugins/tree/main/push-notifications) -
Provides access to native push notifications.
- [Screen Reader](https://github.com/ionic-team/capacitor-plugins/tree/main/screen-reader) -
Provides access to TalkBack/VoiceOver/etc. and Provides simple text-to-speech
capabilities for visual accessibility.
- [Share](https://github.com/ionic-team/capacitor-plugins/tree/main/share) -
Provides methods for sharing content in any sharing-enabled apps the user may
have installed.
- [Splash Screen](https://github.com/ionic-team/capacitor-plugins/tree/main/splash-screen) -
Provides methods for showing or hiding a Splash image.
- [Status Bar](https://github.com/ionic-team/capacitor-plugins/tree/main/status-bar) -
Provides methods for configuring the style of the Status Bar, along with
showing or hiding it.
- [Storage](https://github.com/ionic-team/capacitor-plugins/tree/main/storage) -
Provides a simple key/value persistent store for lightweight data.
- [Text Zoom](https://github.com/ionic-team/capacitor-plugins/tree/main/text-zoom) -
Provides the ability to change Web View text size for visual accessibility.
- [Toast](https://github.com/ionic-team/capacitor-plugins/tree/main/toast) -
Provides a notification pop up for displaying important information to a user.
Just like real toast!
## Tests
Tests are split by backend (API/plugin), CLI, database SQL, and frontend:
- `tests/` - Backend Vitest tests (API + plugin + CLI)
- `playwright/e2e/` - Frontend Playwright tests
- `supabase/tests/` - SQL tests for functions, RLS, and DB logic
Backend test groups (Vitest):
- API tests: public/private endpoints and general backend behavior
- Plugin tests: `tests/updates*.test.ts`, `tests/stats*.test.ts`,
`tests/channel_self*.test.ts`
- CLI tests: `tests/cli*.test.ts` (CLI auth, upload, metadata, etc.)
Run tests:
```bash
# Supabase Edge Functions (default)
bun test:all
bun test:backend
bun test:cli
bun test:front
# CLI workspace
bun run cli:build
bun run cli:test
bun run cli:check
# Legacy aliases kept for compatibility
bun test:local
bun test:all:local
bun test:cli:local
# Database SQL tests (Supabase CLI)
supabase test db
# Cloudflare Workers
bun test:cloudflare:all
bun test:cloudflare:backend
bun test:cloudflare:updates
# Local Cloudflare Workers (required for cloudflare tests)
./scripts/start-cloudflare-workers.sh
```
Notes:
- Tests run in parallel across files. If a test mutates shared data, add
dedicated seed data in `supabase/seed.sql`.
- The repository is a Bun workspace monorepo. The Capgo app lives at the root
and the CLI lives in `cli/`.
- Capgo's Vitest CLI coverage now resolves the local `cli/` workspace by
default, so monorepo changes are exercised together.
- SQL tests in `supabase/tests/` are run by the Supabase CLI test runner.
- Run `bun run supabase:start` first so the local DB is available (worktree-isolated).
## Dev contribution
### Coding Style
- Use Composition API with
[`