Configuration file properties


The app config (config.json) is used for configuring how a project loads in Supervisely. All data is stored in app configuration as key-values, where keys are the string type and values must be in valid JSON format for Supervisely to process it correctly. Otherwise, app might fail. Configuration file must be located at the root of your project, next to the .env file.

Here is a bare-minimum example:

  "name": "Hello World!",
  "version": "2.0.0",
  "entrypoint": "python -m uvicorn src.main:app --host --port 8000"


The Supervisely app config configures many things such as app name, category, icon, poster, docker image and so on. A complete list of available properties with example values is described below. Don't worry, you don't need all of them.


Required property

Name of the app

"name": "Hello World"


App description in Ecosystem

"description": "Working demo, use it as a template for your custom apps


Specifies type of the Ecosystem entity. Default value is "app"\

Available types:

"type": "app"


List of categories that app are associated with in Ecosystem. App can have as many categories as you like.

"categories": [
    "neural network",
    "object detection",
    "detection & tracking",

List of main categories:

Category tags combination

Main categories also contain sub-categories.

If you want your application to appear there you must combine multiple tags. Place order does not matter.

"categories": [
    "annotation transformation",
    "data operations"

List of sub-categories:

  • "images", "videos", "dicom", "pointclouds"

  • "object detection", "semantic segmentation", "instance segmentation", "classification", "interactive segmentation", "metric learning"

  • "detection & tracking", "segmentation & tracking", "interactive segmentation", "interpolation"

  • "annotation transformations", "data transformations", "modality transformations", "projects management", "composition & synthesizing", "augmentation"

  • "train", "serve"


Link to the application icon. If not specified the first two letters of the app name will be displayed as an icon

"icon": "https://your-icon.png"


Stretches the icon to full width. Comparison of icon cover true (left) and false (right)

"icon_cover": false


Icon background color in hex color code format

"icon_background": "#FFFFFF"


Link to the application poster. If not specified displays icon as poster

"poster": "https://your-poster.png"


Required property

App engine version. If you want to use legacy app engine do not specify version property.

"version": "2.0.0"


Required property

Instruction for executing app scripts v2.0.0 app engine only, for legacy apps use main_script property, but not both

src.main ** is a relative path to which contains app object ** :app

"entrypoint": "python -m uvicorn src.main:app --host --port 8000"

Note 1: if app object is in a different script file like, and is imported to script you can specify it like

Note 2: if file is locarted in a path that could cause a conflict with some pip package (ex.: ./supervisely/src/, use --app-dir parameter

"entrypoint": "python -m uvicorn src.main:app --app-dir ./supervisely --host --port 8000"


Use this property if you want to specify certain port (v2.0.0 app engine only)

"port": 8000


Docker image used to run the app. If not specified uses supervisely/base-py-sdk image based on supervisely version in requirements.txt file or uses latest version. List of available supervisely docker images can be found at Dockerhub

"docker_image": "supervisely/base-py-sdk:6.68.6"


Applicable only for Community Edition instances. Users of Enterprise Instances can ignore this field. If flag is False - then the app can not be run on public agents and has to be run only on user's agents. Default value is true.

Practical example: by default users of Community Edition can run apps on the agents (computers) provided by Supervisely team for free. If app, for example, deploys NN inside, Supervisely team can not allow community users to run this app due to the limitation of available GPU resources. That is why some resource-intensive apps have this flag: "community_agent": false

"community_agent": false


Minimum agent version to launch app. Current agent version can be found at the Team Cluster page. List of available agent versions can be found at Dockerhub

"min_agent_version": "6.7.4"


Legacy property

If flag is True the Docker image will be executed with the runtime=nvidia. Selected Docker image must support NVIDIA Container Toolkit.


Specifies whether a GPU is required to run the application. Selected Docker image must support NVIDIA Container Toolkit if "gpu" is "required" or "preferred".

"gpu": "required"

If both flags **gpu**and **need_gpu**are specified, gpu flag will be prioritized

List of available options:

  • "required" - can be run only on agents with GPU

  • "preferred" - сan be run on both GPU and CPU agents (GPU agents prioritized)

  • "no" (or lack of "gpu" property) - сan be run on both GPU and CPU agents


Minimum instance version to launch app. Current instance version can be found at the bottom right corner at the Supervisely

If the current instance version is lower than the version specified in the application, the supervisely platform will try to find a compatible instance version

"min_instance_version": "6.5.50"


Same as min_instance_version``

"instance_version": "6.5.50"


Specifies if app do not use frontend. Set to false for the apps with GUI. Default value is false

"headless": true

Relative path to modal window template from project root

"modal_template": "src/modal.html"

Initializes default values for data variables in modal window

  "modal_template_data": {
    "test_1": "modalDataVal 1",
    "files": null

Initializes default values for state variables in modal window

"modal_template_state": {
    "checkbox_1": false,
    "checkbox_2": true,
    "input": ""


App context menu configuration options. If not specified, app can be launched only from Ecosystem

context_category - sub section in context menu

target - determines where the application can be launched from

"context_menu": {
    "context_category": "Import",
    "target": ["files_folder", "images_project", "images_dataset", "agent_folder"]

List of available context menu targets:

  • "ecosystem"

  • "team"

  • "workspace"

  • "labeling_job"

  • "team_member"

  • "files_folder"

  • "files_file"

  • "agent_folder"

  • "agent_file"

  • "images_project"

  • "images_dataset"

  • "videos_project"

  • "videos_dataset"

  • "volumes_project"

  • "volumes_dataset"

  • "point_cloud_project"

  • "point_cloud_dataset"

  • "point_cloud_episodes_project"

  • "point_cloud_episodes_dataset"


List of session tags. Makes app session available in another app session:

e.g serve YOLOV5 running app session is available in Apply NN to Images Project app session

"session_tags": [

List of available session tags:

  • "sly_video_tracking"

  • "sly_smart_annotation"

  • "deployed_nn"


Integrates app into selected tool.

e.g smart tool app can be used in image annotation tool

"integrated_into": ["image_annotation_tool", "video_annotation_tool"]

List of available options:

  • "panel"

  • "files"

  • "standalone"

  • "image_annotation_tool"

  • "video_annotation_tool"

  • "dicom_annotation_tool"

  • "pointcloud_annotation_tool"


Defines where the task will be displayed on app launch. If specified as "workspace_tasks", app will be displayed in both workspace tasks and app session pages

"task_location": "workspace_tasks"

Available task locations:

  • "workspace_tasks" - suitable for application that directly interacts with data from the workspace (e.g. import/export apps)

  • "application_sessions" - suitable for the application that is tied to the team and can work in multiple workspaces (e.g. server-like apps)


Specifies hotkeys that can be used in app

"hotkeys": [
      {"hotkey": "ctrl+m", "command": "inference"}


Restarts app when certain condition occurs. restart_policy can be found in modal window advanced settings when launching app

"restart_policy": "on_error"


Legacy property

Relative path to main script from project root. Can not be used with v2.0.0 apps, use main_script or entrypoint``

"main_script": "src/"


Legacy property

Relative path to GUI template from project root. Can not be used with v2.0.0 apps.

"gui_template": "src/gui.html"


Application license

"license": {
  "type": "MIT",
  "url": ""

List of available options:

  • "type" - any string

  • "url" - license url (may be empty for the following license types: GPL-3.0 / AGPL-3.0 / Apache-2.0 / BSD-3-Clause / MIT)


If true makes app available only for instance administrators. Default values is false.


App will be available on agents with nvidia driver version same or higher. Requires "gpu": "required"

"min_nvidia_driver_version": "535.54.03"

Configuration examples

Configurations will not vary that much depending on type of the project, whether it's a small headless app or complicated app with UI and a lot of widgets.

Common app config example:

  "name": "App name here",
  "type": "app",
  "version": "2.0.0",
  "categories": ["development"],
  "description": "App description here",
  "entrypoint": "python -m uvicorn src.main:app --host --port 8000"
  "task_location": "workspace_tasks",
  "icon": "https://icon.png",
  "poster": "https://poster.png"

We'll consider a few examples of app configs:

Last updated