Cuitty Code Apps
Installable, permission-scoped apps for Cuitty Code.
Cuitty Code Apps are installable automation units that run against Cuitty Code resources. Apps are owned by a user or organization, published with a versioned manifest, installed into a target owner, and granted only the permissions declared by the app.
Apps can target a user, organization, repository, registry namespace, or package. The target decides which SpiceDB relationships are written for the install and which resources the app can read, write, publish to, or operate.
Required services
- Cuitty Git API for app, install, run, registry, and callback APIs.
- Cuitty Git frontend for market, install, and settings flows.
- Cuitty Auth for browser and API authentication.
- Database for app metadata, installs, grants, and run state.
- SpiceDB for app visibility, install, grant, owner, and run authorization checks.
- Airflow for production app execution.
- Registry artifact storage when apps publish package or image artifacts.
- Optional object storage for larger bundles, logs, and execution artifacts.
Environment variables
PUBLIC_API_URL=http://localhost:4351
PUBLIC_CUITTY_AUTH_URL=http://localhost:7705
AUTH_ISSUER=http://localhost:7705
AUTH_CLIENT_ID=cuitty-git
CUITTY_PUBLIC_URL=http://localhost:4350
CUITTY_GIT_SECRET_KEY=dev-secret-change-me
SPICEDB_ENDPOINT=http://localhost:50051
SPICEDB_PRESHARED_KEY=dev-secret
AIRFLOW_URL=http://localhost:8080
AIRFLOW_USERNAME=airflow
AIRFLOW_PASSWORD=airflow
CUITTY_APP_EXECUTION_MODE=airflow
CUITTY_APP_RUN_CALLBACK_SECRET=dev-callback-secretUse deployment-specific secret management for database URLs, SpiceDB keys, Airflow credentials, registry credentials, and callback HMAC secrets.
Permissions model
The app listing controls discovery and installation. The installation controls runtime access. Manifest-declared permissions are the upper bound: installers can approve fewer grants, but the API rejects grants that the manifest did not declare.
Public apps can be discovered by everyone, private apps are visible only to explicit owners or admins, and organization-visible apps are visible to members of the shared organization. Unauthorized callers may receive 404 when the platform must hide private app existence.
Common workflows
- Publish an app release from an immutable Git tag.
- Review the manifest, docs path, version, requested permissions, and runtime.
- Install the app to a user, organization, repository, registry namespace, or package target.
- Run app actions through Airflow with a scoped installation token.
- Upgrade only after reviewing permission changes.
- Uninstall by revoking grants and disabling app-owned schedules.
Failure modes and recovery
- If SpiceDB is unavailable, security-expanding writes such as app publish and install should fail instead of creating unprotected resources.
- If Airflow submission fails, the app run should record the error and remain failed or retryable.
- If Airflow callbacks are missed, reconciliation should poll Airflow and update terminal run state.
- If an install requests undeclared permissions, reject the install and leave the previous installation unchanged.