Submitting Apps to the Marketplace

Want your app in the Companion App Store? You can submit through our web form or open a pull request to the marketplace repository.

Submit via the web form (recommended)

Visit ci.computer/store-submit  and complete the submission form. You’ll need:

• A Docker image (pre-built, or built with our Static Container Builder)
• A config.json manifest (see config.json reference)
• A docker-compose.json (or .yml) defining services, ports, and volumes
• A metadata/ folder with app description and logo
• A README explaining what the app does and any special setup

After review, approved apps appear in the App Store for all Hub users.

App folder structure

Use Nextcloud  as a reference implementation:

• apps/nextcloud
  • config.json
  • docker-compose.json
  • metadata
    • description.md
    • logo.png
  • README.md

config.json

Required metadata: name, id, port, categories, form_fields, supported_architectures, and more. Use cihub_app_version (not the legacy tipi_version) and set dynamic_config: true for new apps.

{
  "name": "Nextcloud",
  "id": "nextcloud",
  "available": true,
  "short_desc": "A safe home for all your data.",
  "author": "nextcloud",
  "port": 8301,
  "categories": ["data", "featured"],
  "description": "Nextcloud is a suite of client-server software...",
  "version": "latest",
  "source": "https://github.com/nextcloud/server",
  "website": "https://nextcloud.com",
  "exposable": true,
  "supported_architectures": ["arm64", "amd64"],
  "dynamic_config": true,
  "form_fields": [
    {
      "type": "random",
      "label": "Database Password",
      "min": 32,
      "env_variable": "NEXTCLOUD_DB_PASSWORD"
    },
    {
      "type": "text",
      "label": "Admin User",
      "default": "admin",
      "required": true,
      "env_variable": "NEXTCLOUD_ADMIN_USER"
    }
  ],
  "cihub_app_version": 10
}

docker-compose.json

Dynamic compose (schema version 2) is the current format. Define services, internal ports, volumes, health checks, and environment variable references:

{
  "schemaVersion": 2,
  "services": [
    {
      "name": "nextcloud",
      "image": "nextcloud:latest",
      "internalPort": 80,
      "isMain": true,
      "volumes": [
        {
          "hostPath": "${APP_DATA_DIR}/data/nextcloud",
          "containerPath": "/var/www/html"
        }
      ],
      "environment": [
        { "key": "POSTGRES_PASSWORD", "value": "${NEXTCLOUD_DB_PASSWORD}" }
      ]
    }
  ]
}

See Dynamic Compose for the full schema.

metadata/description.md

Long-form description shown on the app’s detail page in the App Store. Supports Markdown/HTML.

metadata/logo.png

Square logo (recommended 256×256 px). Displayed in the App Store grid and app detail page.

README.md

Developer-facing documentation: what the app does, required env vars, architecture notes, and testing instructions for reviewers.

Building your container

You have two paths:

Use an existing Docker image

If your app already publishes to Docker Hub or GHCR, reference that image in docker-compose.json. This is the fastest path for standard open-source apps.

Build with Static Container Builder

For custom agents or apps without a public image, use the Static Container Builder to produce a hermetic, read-only container:

ci-builder init my-app
ci-builder build .
ci-builder package . --output my-app.tar.gz

Upload the resulting image or archive with your store submission.

AI-enabled apps

If your app uses LLMs, add hub_integration.inference to map Hub-resolved AI variables into your app’s env. See AI & Inference.

Agent apps that talk to Hub MCP should set hub_integration.mcp_client: true.

Submit via pull request

Alternatively, fork CI-Marketplace , add your app under apps/<slug>/, and open a PR. Follow the same folder structure and test locally with a custom app store.

Guidelines

• Prefer official upstream Docker images
• Use random form fields for passwords and secrets
• Declare min_hub_version if your app needs a recent Hub feature
• Test on both amd64 and arm64 if you claim both architectures
• Do not bundle telemetry or phone-home behaviour without disclosure