App JSON config

Configuration that connects Python application with Supervisely


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.
YOLOv5 app categories
"categories": [
"neural network",
"object detection",
"detection & tracking",
List of main categories:
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
Comparison of thumbnail with and without spcified 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: if app object is in a different script file like, and is imported to script you can specify it like


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"


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"


"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:
  • "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
"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"
restart policy location


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"

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:
  1. 1.
  2. 2.
  3. 3.