Skip to Content
DocumentationTutorialsPublish your first app

Publish your first app

Take a Docker image and turn it into an entry in the Companion App Store that anyone can install in one click.

Time: ~45 minutes · You’ll need: a published or local Docker image, and a CI Account organization or GitHub account

Companion Hub App Store, Featured view: a search box and category list on the left (All, Expose a port, Alternatives, Featured, Agents, AI, and more), a Companion Intelligence row with Companion Earth, Companion Memory, Companion Planning, and Companion Scan, and a Featured row with Audiobookshelf, Code Server, Collabora Online, and ComfyUICompanion Hub App Store, Featured view: a search box and category list on the left (All, Expose a port, Alternatives, Featured, Agents, AI, and more), a Companion Intelligence row with Companion Earth, Companion Memory, Companion Planning, and Companion Scan, and a Featured row with Audiobookshelf, Code Server, Collabora Online, and ComfyUI
Where you are headed: an entry in the Companion App Store, installable from a Hub in one click.

The path from an app directory to an entry in the Companion App Store:

What you’ll have at the end

  • An app directory that satisfies every marketplace publication and security requirement
  • A verified submission submitted for review — through the cihub submit CLI, the Developer Portal, or, if you have access to the private CI-Marketplace repository, a pull request against it

The four required files

Every app is a directory named for its slug. In the CI-Marketplace repository it lives under apps/<slug>/. All four files are required — missing or empty ones cause the app to be skipped at deploy and rejected by validation tests.

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

Start from the template or scaffold tool

The fastest way to scaffold an app is the interactive generator in the CI-Marketplace repository:

pnpm run new-app

The wizard prompts for your app’s slug, name, description, author, categories, AI inference options, port, source URL, version, and pricing. It immediately tests the generated config.json against the schema with Zod so you know right away if it is valid.

Alternatively, copy the repository template:

cp -r apps/_template apps/my-app

Or manually create a folder named my-app with the files described below. The slug you choose is your app’s unique identity — the directory name and the id in config.json must match.

Write config.json

Required fields for all apps:

FieldTypeNotes
idstringMust match the directory name (e.g. my-app)
namestringHuman-readable display name shown in the store
versionstringSemver recommended (e.g. 1.0.0)
short_descstringOne line, 500 characters or fewer
authorstringYou, your organization, or the upstream maintainer
portnumberPrimary host port (1024–65535); omit for no_gui and mcp apps
sourcestringURL to the source repository
categoriesstring[]Valid tags e.g. ["utilities"], ["ai"], ["data"]
availablebooleantrue → published; false → ingested as a hidden draft
supported_architecturesstring[]e.g. ["arm64", "amd64"]
cihub_app_versionnumberInteger manifest version (start with 1)

A minimal valid config.json:

{ "id": "my-app", "name": "My App", "version": "1.0.0", "short_desc": "A lightweight self-hosted utility.", "author": "your-name", "port": 8080, "source": "https://github.com/you/my-app", "categories": ["utilities"], "available": true, "supported_architectures": ["arm64", "amd64"], "cihub_app_version": 1, "privacy": { "declared_by": "Your Name", "declared_at": "2026-10-26", "collects": [] } }

Privacy declarations: The store’s App Privacy card is driven by the privacy block. An empty "collects": [] is an affirmative statement that the app collects no user data. If your app collects diagnostics, usage data, or credentials, declare those categories. An absent privacy block is rendered as “Not declared”.

Write docker-compose.json

Dynamic compose (schema version 2) defines your container services. Exactly one service must be marked "isMain": true.

{ "schemaVersion": 2, "services": [ { "name": "my-app", "image": "myorg/my-app:1.0.0", "internalPort": 8080, "isMain": true, "volumes": [ { "hostPath": "${APP_DATA_DIR}/data", "containerPath": "/data" } ], "environment": [{ "key": "APP_ENV", "value": "production" }] } ] }

Pin a real image tag or @sha256: digest rather than :latest. Users receive whatever the tag resolves to at install time. In addition, bind mounts in volumes must start with ${APP_DATA_DIR} (or /etc/localtime / /etc/timezone), and services cannot set privileged: true, networkMode: "host", pid: "host", or non-default Linux capabilities unless explicitly granted in Hub’s TRUSTED_APP_SECURITY_ALLOWLIST.

Runtime DRM, Kata Containers, and Confidential Containers

Standard Docker containers share the host Linux kernel and store unencrypted layers on disk (/var/lib/docker/overlay2). On user-owned appliance hardware such as Companion Hub, the operator holds root privileges on the host. Packaging an application in a standard container provides distribution, not DRM — anyone with host access can execute docker exec, extract proprietary binaries or model weights, inspect unencrypted layers, or dump RAM via /proc/<pid>/mem.

To protect commercial software and proprietary intellectual property, Companion Hub supports microVM container isolation and hardware-enforced Confidential Containers (CoCo) via the runtime property in docker-compose.json:

{ "schemaVersion": 2, "services": [ { "name": "my-app", "image": "myorg/my-app:1.0.0", "runtime": "kata-cc", "internalPort": 8080, "isMain": true, "volumes": [ { "hostPath": "${APP_DATA_DIR}/data", "containerPath": "/data" } ], "environment": [{ "key": "APP_ENV", "value": "production" }] } ] }

Supported container runtimes include:

  • kata / kata-qemu / kata-clh: Launches the container workload inside a dedicated, lightweight Kata Containers  microVM (using QEMU or Cloud Hypervisor). This establishes a hardware-enforced hypervisor boundary between the host OS and container processes.
  • kata-cc (Confidential Containers): Implements the Confidential Containers architecture  utilizing hardware-based Trusted Execution Environments (TEEs) such as AMD SEV-SNP, Intel TDX, and ARM CCA.
    • Hardware memory encryption: Guest RAM is encrypted by the CPU hardware memory controller using hardware-generated keys; host root cannot inspect or dump process memory.
    • Encrypted container layers in R2: Image layers remain encrypted in transit and in object storage. Decryption keys are released via remote attestation directly to the guest microVM enclave by a Key Broker Service (KBS).
    • Host tampering prevention: The host hypervisor and operator cannot inspect, extract, or modify the container filesystem, providing true runtime DRM on customer hardware.
  • metadata/description.md — Markdown long description for your app detail page.
  • metadata/logo.png or logo.jpg — Square icon (256×256 px recommended); must not be 0 bytes.
  • metadata/screenshots/ — Optional gallery screenshots (.png, .jpg). Required before promotion to Verified or Featured.

Test and capture verification evidence

Before submitting, verify that your app boots cleanly:

  • Local verification runner (in CI-Marketplace repo):
    deno run -A scripts/verify-apps.ts --slugs my-app
    This starts the container stack in Docker, runs healthchecks, and saves a Playwright screenshot to verification-results/screenshots/my-app.png.
  • Copy that verified screenshot to:
    e2e/screenshots/my-app.png
    This serves as permanent QA evidence that the container runs and serves its GUI on appliance hardware.

Submit your app

Pick the submission route that fits your workflow:

  1. CLI (cihub submit) — Recommended for community and private developers:
    cihub login cihub submit --dry-run ./my-app cihub submit ./my-app
    The CLI automatically tags and pushes your local Docker container layers to the secure Portal registry backed by Cloudflare R2 object storage (docker/<name>/blobs/<digest>), rewrites docker-compose.json to reference the Portal registry, packages the .tar.gz archive, and submits the app to Portal as pending review. R2 storage ensures scalable, zero-egress distribution and encrypted blob storage with Portal device authentication.
  2. Developer Portal (hub.ci.computer/developer): Organization owners and admins can log into the Developer apps dashboard to mint developer tokens, manage listings, and upload pre-packaged .tar.gz bundles.
  3. Pull request against CI-Marketplace: If you have repository access, commit your apps/<slug>/ folder and e2e/screenshots/<slug>.png and open a PR against the dev branch.

Testing before you submit

When iterating on a private, commercial, or new app before publishing to the entire community:

  1. Submit as a hidden draft: Set "available": false in config.json. The app is ingested, and its container layers are stored in the secure Portal R2 registry. It deploys to the catalog as a draft, but stays hidden from the public App Store browsing views.
  2. Install on your own Hub: On a Hub paired to your organization, you can test-install your draft application directly. Hub authenticates against the Portal registry using your device key, pulls the container layers from R2, launches them with your designated runtime (runc, kata, or kata-cc), and confirms that database migrations run, volumes persist data across container restarts, and exposure settings work.
  3. Promote to published: Once you confirm that everything works and your verification screenshot is captured, set "available": true to publish the listing for all users.

Why not use manual app store URLs or call the API directly?

In earlier pre-Companion-Hub releases, custom app stores could be added by pointing Hub at a manual Git repository URL. In Companion Hub, the dashboard’s Settings → App Stores → Add App Store dialog displays “Feature coming soon — Custom app store setup is under maintenance. Your Hub uses the CI Marketplace automatically; no manual store URL is needed.”

Why not call the API directly? The Hub backend does still serve an app-store creation endpoint (POST /api/marketplace/create), so the capability was not deleted from the server. It is not a supported path — nothing in the UI manages a store created that way, and the request shape is not guaranteed — so it is not documented as a workaround here.

Whether the dialog returns is genuinely unsettled: the dialog text says “coming soon”, while the comment in the source that disabled it describes manual store URLs as a removed pre-Companion-Hub feature. The supported path remains unsettled.

Furthermore, legacy Git stores only cloned static YAML files from Git repositories — they cannot store container blobs on Cloudflare R2, lack registry authentication, and offer zero runtime DRM or hardware-enforced TEE isolation. The supported, secure architecture for distributing private container apps is pushing containers to the Portal R2 registry with "available": false.

Next

Last updated on