Cirro App Kit

Documentation, a project template and tools for building browser apps on the Cirro platform: apps that sign users in with their Cirro account over OAuth and work with their projects, datasets and files.

The developer guide is also published as a website: Cirro App Kit docs.

Quick start

New to Cirro? Read Cirro in five minutes, then follow getting started, which takes you from no account to a running app.

1. Register the app's callback URL. Each app has its own callback URL, the address it returns to after sign-in, and gets its client ID from the tenant by it. In production a tenant admin registers it with discovery enabled (support@cirro.bio for the public tenant), so no client ID is configured or deployed. For local development, an App Developer can register a localhost callback URL themselves and put that registration's client ID in .env.
2. Run the app template. templates/app is a React starter for portals, dashboards and workflow tools. Set the tenant's address (and, for local development, your registration's client ID) in .env, then npm install && npm run dev.
3. Decide what to build. Cirro gives an app storage, pipelines, workspaces, sharing and a database, not just an API; see building on Cirro. List the permissions you use in cirro-permissions.json (permissions).
4. Before deploying, run python3 tools/scan.py <your app> and work through the security checklist.
5. Connect to tenants. A deployed app works for users once each tenant approves it; see connecting to tenants.

What's here

Path	Contents
docs/	The developer guide
templates/app	Buildable starter app: sign-in, projects, datasets
tools/scan.py	Pre-deploy scanner for common security and configuration mistakes
tools/api_surface.py	Regenerates the API reference for any installed version of the packages
reference/	Generated API method list and common response models
skills/	Optional Claude skills that use these docs; see Using with Claude

Developer guide

• Cirro in five minutes: what tenants, projects, datasets, pipelines and the rest are
• Getting started: from no account to a running app
• Building on Cirro: why build on Cirro, what an app can do with each part of the platform, architectural patterns, trust boundaries
• Connecting to tenants: how a deployed app gets connected to and approved in Cirro tenants, including the public tenant; serving several tenants
• Permissions: the app's permission manifest, checking user roles, and degrading gracefully when users can't do everything
• App types and registration: the front-end-only Public App model, who registers an app, redirect URIs, permissions, approval
• Architecture: the front-end-only model: a client ID, no secret, and users who sign in as themselves
• Cirro TypeScript packages: which @cirrobio package does what, and known issues
• Authentication: the sign-in flow and the template's auth provider
• Calling the API: DataService, pagination, errors
• Sheets: relational tables in the project as the app's database; schemas, views, SQL, ingest
• Working with files: file credentials, signed URLs, uploads
• Workspaces: interactive containers launched by the app; boot time, the per-user limit, handing off in a new tab, auto-stop
• Deployment: build config, hosting, Content Security Policy
• Security checklist
• Troubleshooting

Verified against

@cirrobio/api-client and @cirrobio/sdk 0.13.39, with oidc-client-ts 3.5.0 for sign-in, React 19, Vite 8 and TypeScript 7. The app template was clean-installed and built on 2026-10-19. CI rebuilds it on every push and weekly against the latest published packages.

Contributing

See contributing, including how to update the kit when the Cirro packages publish a new version.

Using with Claude

The kit is also a Claude Code plugin, and its repository is a marketplace that lists it. Its skills hold the workflow steps for an agent (which questions to ask, which path to choose, when to verify against installed versions) and read their facts from this guide, so the guide stays the single source of truth. Install it in Claude Code (you need access to the CirroBio/Cirro-app-kit repository):

/plugin marketplace add CirroBio/Cirro-app-kit
/plugin install cirro-app-kit@cirro-app-kit

Then describe what you want to build ("start a Cirro dashboard that lists my datasets"); the matching skill loads by itself, or call one by name, such as /cirro-app-kit:cirro-app-scaffold. To work on the skills, see contributing.

Skill	Use it to
cirro-app-scaffold	Start a new app
cirro-auth-wiring	Add or debug Cirro sign-in
cirro-data-access	Call the API and read or upload files
cirro-permissions	Write the permission manifest and handle 403s
cirro-sheets	Use Sheets as the app's database
cirro-compute	Run pipelines and launch workspaces from the app
cirro-app-review	Review an app before deploying
cirro-app-deploy	Deploy, and connect the app to tenants