Skip to main content
Private beta

Code App Market

Publish, share, install, and manage Cuitty Code Apps.

HTML Markdown JSON

The Code App Market is the browser surface for discovering, installing, and managing Cuitty Code Apps. It uses the Cuitty Code API and the same owners, organizations, slugs, visibility semantics, and SpiceDB relationships as repositories. Registry namespace and package targets are available when Cuitty Registry integration is configured.

Required services

  • Cuitty Code API and frontend.
  • Cuitty Auth.
  • Database for app listings, versions, installs, and profile docs.
  • SpiceDB for listing visibility, install, manage, and publish checks.
  • Airflow for app publishing and runtime workflows.
  • Object storage or Cuitty Registry when listings include bundles, artifacts, or package output.

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-git
SPICEDB_ENDPOINT=https://spicedb.example.com:50051
SPICEDB_PRESHARED_KEY=cuitty-safe:acme/prod/spicedb-preshared-key
AIRFLOW_URL=https://airflow.example.com
CUITTY_APP_EXECUTION_MODE=airflow

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
SPICEDB_ENDPOINT=http://localhost:50051
SPICEDB_PRESHARED_KEY=<local-dev-only-spicedb-key>
AIRFLOW_URL=http://localhost:8080
CUITTY_APP_EXECUTION_MODE=airflow
PUBLIC_REGISTRY_URL=http://localhost:4371

Routes

  • /market/apps lists discoverable apps.
  • /market/apps/:owner/:app shows README, permissions, versions, and metadata.
  • /market/apps/:owner/:app/install reviews requested permissions and installs the app.
  • /market/apps/:owner/:app/versions lists published versions.
  • /market/apps/:owner/:app/settings manages owner-controlled metadata and visibility.

Permissions model

Apps can be public, private, or organization-visible. Public discovery does not automatically mean public install; app owners can still restrict who may install an app. Private and organization-visible apps should return not found to unauthorized users when hiding existence is required.

Operators should verify that market search, detail, install, and settings routes all use the same authorization policy.

Common workflows

  1. Publish a listing from a repository release and .cuitty/app.toml manifest.
  2. Show README or manifest docs from the configured docs path.
  3. Review requested permissions before installation.
  4. Install to the selected user, organization, repository, or Registry namespace/package target.
  5. Manage versions, metadata, and visibility from the listing settings page.

Failure modes and recovery

  • If manifest validation fails, leave the existing listing and latest stable version untouched.
  • If requested grants are outside the manifest, reject the install and show the API error.
  • If SpiceDB relationship writes fail, pause security-expanding market changes and replay the authz outbox.
  • If the market UI cannot reach the API, confirm PUBLIC_API_URL and frontend proxy configuration.

E2E checks

From the tests directory in the Cuitty Code repository:

bun run test:e2e:apps-registry -- --project=chromium
bun run test:e2e:apps-registry:headed

The mocked specs set local browser auth state and intercept API responses by API path, so both direct API calls on http://localhost:4351/api/v1/... and proxied frontend calls on http://localhost:4350/api/v1/... are covered.