{
  "slug": "code/apps",
  "title": "Cuitty Code Apps",
  "description": "Installable, permission-scoped apps for Cuitty Code.",
  "url": "https://cuitty.com/docs/code/apps",
  "markdown_url": "https://cuitty.com/docs/code/apps.md",
  "json_url": "https://cuitty.com/docs/code/apps.json",
  "frontmatter": {
    "title": "Cuitty Code Apps",
    "description": "Installable, permission-scoped apps for Cuitty Code.",
    "order": 10,
    "section": "Code",
    "updatedAt": "2026-05-24"
  },
  "headings": [
    {
      "depth": 2,
      "slug": "required-services",
      "text": "Required services"
    },
    {
      "depth": 2,
      "slug": "environment-variables",
      "text": "Environment variables"
    },
    {
      "depth": 2,
      "slug": "permissions-model",
      "text": "Permissions model"
    },
    {
      "depth": 2,
      "slug": "common-workflows",
      "text": "Common workflows"
    },
    {
      "depth": 2,
      "slug": "failure-modes-and-recovery",
      "text": "Failure modes and recovery"
    },
    {
      "depth": 2,
      "slug": "related-pages",
      "text": "Related pages"
    }
  ],
  "body_markdown": "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.\n\nApps 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.\n\n## Required services\n\n- Cuitty Code API for app, install, run, and callback APIs.\n- Cuitty Code frontend for market, install, and settings flows.\n- Cuitty Auth for browser and API authentication.\n- Database for app metadata, installs, grants, and run state.\n- SpiceDB for app visibility, install, grant, owner, and run authorization checks.\n- Airflow for production app execution.\n- Cuitty Registry when apps publish package or image artifacts.\n- Optional object storage for larger bundles, logs, and execution artifacts.\n\n## Environment variables\n\nProduction deployments should keep secret values behind Safe references. The reference syntax is `cuitty-safe:account/safe/secret`; only the resolver sees the decrypted value.\n\n```dotenv\nPUBLIC_API_URL=https://code.example.com\nPUBLIC_CUITTY_AUTH_URL=https://auth.example.com\nAUTH_ISSUER=https://auth.example.com\nAUTH_CLIENT_ID=cuitty-code\nCUITTY_PUBLIC_URL=https://code.example.com\nCUITTY_CODE_SECRET_KEY=cuitty-safe:acme/prod/cuitty-code-secret-key\nSPICEDB_ENDPOINT=https://spicedb.example.com:50051\nSPICEDB_PRESHARED_KEY=cuitty-safe:acme/prod/spicedb-preshared-key\nAIRFLOW_URL=https://airflow.example.com\nAIRFLOW_USERNAME=airflow-service\nAIRFLOW_PASSWORD=cuitty-safe:acme/prod/airflow-password\nCUITTY_APP_EXECUTION_MODE=airflow\nCUITTY_APP_RUN_CALLBACK_SECRET=cuitty-safe:acme/prod/app-run-callback-secret\nPUBLIC_REGISTRY_URL=https://registry.example.com\n```\n\nFor an isolated local development stack only, use disposable placeholder values and local endpoints:\n\n```dotenv\nPUBLIC_API_URL=http://localhost:4351\nPUBLIC_CUITTY_AUTH_URL=http://localhost:7705\nAUTH_ISSUER=http://localhost:7705\nAUTH_CLIENT_ID=cuitty-code\nCUITTY_PUBLIC_URL=http://localhost:4350\nCUITTY_CODE_SECRET_KEY=<local-dev-only-code-secret-key>\nSPICEDB_ENDPOINT=http://localhost:50051\nSPICEDB_PRESHARED_KEY=<local-dev-only-spicedb-key>\nAIRFLOW_URL=http://localhost:8080\nAIRFLOW_USERNAME=airflow\nAIRFLOW_PASSWORD=<local-dev-only-airflow-password>\nCUITTY_APP_EXECUTION_MODE=airflow\nCUITTY_APP_RUN_CALLBACK_SECRET=<local-dev-only-callback-secret>\nPUBLIC_REGISTRY_URL=http://localhost:4371\n```\n\nThe 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.\n\n## Permissions model\n\nThe 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.\n\nPublic 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.\n\n## Common workflows\n\n1. Publish an app release from an immutable Git tag.\n2. Review the manifest, docs path, version, requested permissions, and runtime.\n3. Install the app to a user, organization, repository, or Registry namespace/package target.\n4. Run app actions through Airflow with a scoped installation token.\n5. Upgrade only after reviewing permission changes.\n6. Uninstall by revoking grants and disabling app-owned schedules.\n\n## Failure modes and recovery\n\n- If SpiceDB is unavailable, security-expanding writes such as app publish and install should fail instead of creating unprotected resources.\n- If Airflow submission fails, the app run should record the error and remain failed or retryable.\n- If Airflow callbacks are missed, reconciliation should poll Airflow and update terminal run state.\n- If an install requests undeclared permissions, reject the install and leave the previous installation unchanged.\n\n## Related pages\n\n- [Code App Market](/docs/code/app-market)\n- [App permissions](/docs/code/app-permissions)\n- [App execution with Airflow](/docs/code/app-execution-airflow)\n- [Authorization with SpiceDB](/docs/code/authz-spicedb)\n- [Operator runbook](/docs/code/operator-runbook)\n- [Registry code integration](/docs/registry/code-integration)",
  "links_out": [
    "/docs/code/app-market",
    "/docs/code/app-permissions",
    "/docs/code/app-execution-airflow",
    "/docs/code/authz-spicedb",
    "/docs/code/operator-runbook",
    "/docs/registry/code-integration"
  ]
}