Skip to main content
Private beta

Cuitty Code Apps

Installable, permission-scoped apps for Cuitty Code.

HTML Markdown JSON

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, or a Cuitty Registry namespace/package when Registry integration is enabled. 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 Code API for app, install, run, and callback APIs.
  • Cuitty Code 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.
  • Cuitty Registry when apps publish package or image artifacts.
  • Optional object storage for larger bundles, logs, and execution artifacts.

Environment variables

Production deployments should keep secret values behind Safe references. The reference syntax is cuitty-safe:account/safe/secret; only the resolver sees the decrypted value.

PUBLIC_API_URL=https://code.example.com
PUBLIC_CUITTY_AUTH_URL=https://auth.example.com
AUTH_ISSUER=https://auth.example.com
AUTH_CLIENT_ID=cuitty-code
CUITTY_PUBLIC_URL=https://code.example.com
CUITTY_CODE_SECRET_KEY=cuitty-safe:acme/prod/cuitty-code-secret-key
SPICEDB_ENDPOINT=https://spicedb.example.com:50051
SPICEDB_PRESHARED_KEY=cuitty-safe:acme/prod/spicedb-preshared-key
AIRFLOW_URL=https://airflow.example.com
AIRFLOW_USERNAME=airflow-service
AIRFLOW_PASSWORD=cuitty-safe:acme/prod/airflow-password
CUITTY_APP_EXECUTION_MODE=airflow
CUITTY_APP_RUN_CALLBACK_SECRET=cuitty-safe:acme/prod/app-run-callback-secret
PUBLIC_REGISTRY_URL=https://registry.example.com

For an isolated local development stack only, use disposable placeholder values and local endpoints:

PUBLIC_API_URL=http://localhost:4351
PUBLIC_CUITTY_AUTH_URL=http://localhost:7705
AUTH_ISSUER=http://localhost:7705
AUTH_CLIENT_ID=cuitty-code
CUITTY_PUBLIC_URL=http://localhost:4350
CUITTY_CODE_SECRET_KEY=<local-dev-only-code-secret-key>
SPICEDB_ENDPOINT=http://localhost:50051
SPICEDB_PRESHARED_KEY=<local-dev-only-spicedb-key>
AIRFLOW_URL=http://localhost:8080
AIRFLOW_USERNAME=airflow
AIRFLOW_PASSWORD=<local-dev-only-airflow-password>
CUITTY_APP_EXECUTION_MODE=airflow
CUITTY_APP_RUN_CALLBACK_SECRET=<local-dev-only-callback-secret>
PUBLIC_REGISTRY_URL=http://localhost:4371

The local placeholders above are for disposable developer stacks only. Use deployment-specific Safe references 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

  1. Publish an app release from an immutable Git tag.
  2. Review the manifest, docs path, version, requested permissions, and runtime.
  3. Install the app to a user, organization, repository, or Registry namespace/package target.
  4. Run app actions through Airflow with a scoped installation token.
  5. Upgrade only after reviewing permission changes.
  6. 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.