Developer apps and publishing

The Developer apps dashboard at hub.ci.computer/developer provides organization owners and administrators with self-service tools to publish and manage applications in the Companion App Store.

From this dashboard, you can view your organization’s app catalog listings, inspect version deployment across environments, mint developer API tokens for the cihub CLI, onboard with Stripe Connect for commercial distribution, and upload app packages directly.

Managing developer apps and minting developer tokens requires an Owner or Admin role in your organization. Regular members can view apps in the store but cannot submit or manage listings.

flowchart TD
    dev["Developer Workspace<br/>apps/<slug>/ manifest & compose"] --> auth{"Publish method"}
    auth -->|"CLI (recommended)"| cli["cihub login<br/>cihub submit ./my-app"]
    auth -->|"Web dashboard"| web["hub.ci.computer/developer<br/>Upload .tar.gz bundle"]
    cli -->|"Pushes images to Portal registry<br/>Submits bundle"| ingest["Portal Ingest API<br/>POST /api/organizations/:orgId/apps/ingest"]
    web -->|"Requires pre-hosted images"| ingest
    ingest -->|"status: pending"| queue["Review Queue<br/>CI-App-Review client"]
    queue -->|"Verification pass"| channels{"Publish channel"}
    channels -->|"dev channel"| devEnv["hub.companionintelligence.com"]
    channels -->|"prod channel"| prodEnv["hub.ci.computer (All users)"]

Features

1. Catalog listing status and version tracking

The Listings section shows every application submitted under your active organization. Each listing displays:

App title and icon: Display identity rendered in the Companion App Store.
Review status: pending (under review by maintainers), published (visible to users), or draft (hidden from general browsing).
Environment versions:
- Live version: Currently deployed to production on hub.ci.computer.
- Staging version: Currently on the staging environment (hub.companionintel.com).
- Dev version: Currently active on hub.companionintelligence.com.
Pricing model: Indicates whether the app is free, paid, or freemium.

2. Developer tokens (`cio_...`)

Developer tokens authenticate the cihub CLI and automated CI/CD pipelines to publish app bundles and manage catalog listings on behalf of your organization.

To generate a token:

Open Developer tokens

Navigate to hub.ci.computer/developer and scroll to the Developer tokens card.

Name your token

Enter a descriptive name (e.g. laptop-cli or github-actions-publisher) in the token name field.

Mint and copy

Select Create Token. The generated token (prefixed with cio_) is displayed once. Copy and store it securely; it cannot be retrieved after leaving the page.

To revoke a compromised or retired token, select Revoke beside the token in the list. Revocation takes effect immediately across all Portal endpoints.

Tokens carry the catalog:write scope by default. Never commit developer tokens into git repositories or embed them in container images.

3. Submitting an app bundle via web upload

You can upload a packaged application archive (.tar.gz, up to 10 MB) directly from the Submit bundle card.

The uploaded archive must contain:

- config.json
- docker-compose.json
- - description.md
  - logo.png

Registry requirement for community apps: Portal enforces that all community app container images are hosted on the Portal registry. If your docker-compose.json references third-party images (such as Docker Hub or GHCR), the web upload rejects the bundle with IMAGE_NOT_PORTAL. For automated image tagging, registry authentication, and image pushing, use cihub submit instead of manual web upload. See Submitting to the Marketplace.

4. Commercial monetization with Stripe Connect

When commercial app sales are enabled (store.paidApps), the Payouts card lets organization owners connect a Stripe account via Stripe Connect.

Select Set up payouts to launch the Stripe onboarding workflow.
Complete business and identity verification on Stripe.
Once verified, charges and payouts are enabled for your organization, allowing you to publish paid apps or subscriptions in the Companion App Store (routed via Stripe Connect destination charges when store.connectDestination is enabled). When a customer organization buys a paid app, the Stripe webhook writes an app_entitlement record for that organization, and GET /api/store/:id/install verifies that entitlement via the Hub’s x-device-key before delivering the install bundle.

Review and publication lifecycle

When an app bundle is uploaded (either via web upload or cihub submit):

Ingest as pending: The app is ingested into Portal with status pending. It does not appear in the public App Store immediately.
Catalog review: Maintainers test the submission in an isolated sandbox environment using the CI-App-Review tool. Reviewers verify:
- Clean container installation and startup.
- Security sandbox conformance (no disallowed host root binds or root Docker socket passthroughs without explicit allowlist exemption).
- Valid privacy declarations and appropriate credential defaults.
- GUI and Playwright screenshot evidence.
Channel approval: Reviewers approve the app for dev (for developer and testing appliances) and then promote to prod (production Companion App Store for all users).