Details of all options available in config.json

When adding a new app to the Companion App Store, you need to create a config.json file in the app’s folder. This file contains all the information needed to run the app. Below you can find all the options available in the config.json file.

Three parts of the manifest end up as environment variables in the running container: form_fields ask the user for values at install time, hub_integration.mcp_client injects Hub’s MCP endpoint, and hub_integration.inference maps Hub’s model settings onto the variable names your app expects:

flowchart TD
    C["config.json"] -->|"form_fields"| F["Install form,<br/>validated per type"]
    C -->|"hub_integration"| HI["Hub-provided values<br/>mcp_client: HUB_URL, HUB_MCP_URL,<br/>HUB_MCP_API_KEY, HUB_WAKE_SECRET<br/>inference: llm_base_url, chat_model, …<br/>as your own names"]
    F -->|"one env_variable<br/>per field"| E["App environment"]
    HI --> E
    E -->|"${VARIABLE} references"| D["docker-compose.json"]
    D --> R["Running app"]

Sometimes an app requires additional information to run, such as a username or a password. Use the form_fields property in the config.json file to request that information. Here’s an example:

{
  "form_fields": [
    {
      "type": "text",
      "label": "Username",
      "max": 50,
      "min": 3,
      "required": true,
      "env_variable": "NEXTCLOUD_ADMIN_USER"
    },
    {
      "type": "password",
      "label": "Password",
      "max": 50,
      "min": 3,
      "required": true,
      "env_variable": "NEXTCLOUD_ADMIN_PASSWORD"
    }
  ]
}

You can choose between different types of fields. The app will automatically validate the user input before submitting.

Here is a table of the available form_field properties:

Using options in form fields

You can create a form field with options like this in your config.json. It will be rendered as a multi-select dropdown in the UI. label is what will be shown to the user and value is the actual value the environment variable will be set to when the corresponding option is selected.

{
  "label": "Select your favorite fruits",
  "type": "text",
  "required": true,
  "options": [
    { "label": "Apple", "value": "apple" },
    { "label": "Banana", "value": "banana" },
    { "label": "Orange", "value": "orange" }
  ],
  "env_variable": "fruits"
}

Hub integration (hub_integration)

Apps can opt in to Hub-provided environment variables and services.

MCP client

First-party agent apps ci-openclaw and ci-hermes ship with hub_integration.mcp_client: true by default so Hub MCP is wired automatically on install. Other agent apps can opt in the same way:

{
  "hub_integration": {
    "mcp_client": true,
    "wake_endpoint": "/hooks/hub-wake",
    "wake_port": 3000,
    "sse_events": false
  }
}

wake_endpoint defaults to /hooks/hub-wake. ci-openclaw sets it to /hooks/wake and sets wake_port to its setup and proxy port, 18789. Hermes declares no wake registration.

When enabled, Hub injects HUB_URL, HUB_MCP_URL, HUB_MCP_API_KEY, and HUB_WAKE_SECRET into the app’s environment. HUB_MCP_API_KEY is a key Hub creates for that app alone and revokes when you uninstall it.

An app with mcp_client: true publishes its host port on 127.0.0.1 only, because it holds a key that can drive the Hub. Reach it from another device through Private VPN or the public web.

Inference variables

AI apps map standardized Hub inference keys to their own env variable names:

{
  "hub_integration": {
    "inference": {
      "llm_base_url": "LLM_API_BASE",
      "llm_api_key": "LLM_API_KEY",
      "chat_model": "LLM_DEFAULT_CHAT_MODEL",
      "embedding_model": "LLM_DEFAULT_EMBEDDING_MODEL",
      "vision_model": "LLM_DEFAULT_VISION_MODEL",
      "ollama_host": "OLLAMA_HOST"
    }
  }
}

See AI & Inference for resolution order and setup.

Other options