project.yaml Configuration Reference

project.yaml is the core configuration file for UGOS Pro applications, used to define basic information, runtime configuration, and display information. When packaging the project with the ugcli tool, it validates and creates the final installation package based on this configuration file.

Basic Configuration

Field	Type	Required	Description
spec_version	string	Yes	Configuration specification version. Current version is `2.1`
app_id	string	Yes	Application ID used by the system to identify the application. Cannot be modified after the application is published. Naming convention: `com.company_or_organization.app_name`, can only contain lowercase letters, numbers, and dots, and must start with a letter. Example: `com.mycompany.myapp`
version	string	Yes	Application version in the format `x.y.z`, where x is the major version, y is the minor version, and z is the patch version. Example: `0.1.0` The build number is appended during packaging via `--build`, producing the final version `x.y.z.b` (`b` is a 4-digit zero-padded build number, e.g. `0.1.0.0001`). See Version Number Rules.
support_arch	string[]	Yes	List of supported CPU architectures. Valid values: `amd64`, `arm64`
supports	string[]	No	Client types supported by the application. Multiple values allowed. Valid values: - `app`: Mobile - `pc`: Desktop - `tv`: TV If omitted or empty, packaging defaults to `app` and `pc`.
tag_types	string[]	Yes	Application categories for classification display. Valid values: - `system`: System Management - `media`: Entertainment - `utility`: Utilities - `security`: Security - `download`: Download - `backup`: Backup - `devtool`: Development Tools

Version Number Rules

The application version consists of major (x), minor (y), patch (z), and build (b) segments in the format x.y.z.b (b is a 4-digit zero-padded build number, e.g. 0.1.0.0001).

Segment	Description	Configuration Location
x.y.z	Major / minor / patch version	`version` field in `project.yaml`
b	Build number (4-digit, zero-padded)	Specified via `ugcli pack --build <n>`

Rules:

Under the same x.y.z version, each new package submission must use an incremented build number. Duplicate build numbers are not allowed.
Version comparison is numeric segment by segment. A higher number means a newer version. For example, 1.0.1.0002 is newer than 1.0.1.0001, and 1.1.0.0000 is newer than 1.0.9.9999.
Set x.y.z in project.yaml. Running ugcli pack --build 1 produces the final version 0.1.0.0001.

Example:

shell

# project.yaml: version: 0.1.0
ugcli pack --build 1   # final version 0.1.0.0001
ugcli pack --build 2   # final version 0.1.0.0002 (build number must increase under the same x.y.z)

Runtime Configuration

Field	Type	Required	Description
start_cmd	string	Yes*	Startup command for the application backend service, including the backend service executable path (relative to the application installation directory) and command-line arguments. Example: `bin/myapp_serv --port=21010` *Not required for Docker applications.
port	number	Yes	Port number the application backend service listens on for HTTP services. Example: `21010`
proxy_path	string	No	HTTP request path prefix for the system gateway to proxy. Used to forward frontend requests to the backend service. For example, if set to `api/v1`, all requests starting with `/api/v1/` will be forwarded to the backend service.
open_type	string	Yes	How the application interface opens. Valid values: - `inner`: Opens as an independent window within the system desktop. - `tab`: Opens as a new tab in the browser.
depend_fw_version	string	No	Minimum required UGOS Pro firmware version in the format `x.y.z.b` (`b` is a 4-digit zero-padded build number). Applies to all application types. Example: `1.13.0.0000`
is_docker_app	boolean	No	Whether this is a Docker application. Set to `true` for Docker apps. See Docker Application Development.
depend_docker_version	string	No*	Minimum required Docker suite version in the format `x.y.z.b` (`b` is a 4-digit zero-padded build number). Example: `1.7.0.0000` *Required for Docker applications.

Firmware Version Number

depend_fw_version is optional and applies to both native and Docker applications. If you need to declare a minimum firmware requirement, the value must match the actual UGOS Pro system version. Please contact UGREEN developers to obtain valid firmware version numbers to avoid installation or runtime failures caused by incorrect version values.

If your application uses built-in system capabilities (such as specific APIs, system services, or suite features), ensure the declared minimum firmware version is equal to or higher than the firmware version that first provides those capabilities. This prevents functional issues when users install the application on older firmware.

Application Dependencies

Some applications require other installed suites on the system. Dependencies are written into the package configuration during packaging and checked before installation.

Docker Application Dependency

Docker applications must set depend_docker_version to declare the minimum Docker suite version. During packaging, ugcli automatically generates:

Dependency App ID	Dependency Type	Version Source
`com.ugreen.docker`	MustDepend	`depend_docker_version` field

Example:

yaml

is_docker_app: true
depend_fw_version: 1.13.0.0000
depend_docker_version: 1.7.0.0000

Before installing a Docker application, users must ensure the Docker suite (com.ugreen.docker) is installed at a version not lower than depend_docker_version.

Feature Configuration

Field	Type	Required	Description
support_migration	boolean	No	Whether migration of the installation directory is supported. Default: `false`
allow_add_access_path	boolean	No	Whether users can authorize the application to access Personal Folder and Shared Folder. Default: `false`
only_admin	boolean	No	Whether the application is accessible to administrators only. Default: `false`

Application Links and Compliance Information

The following fields provide compliance and support links displayed on the application detail page. Each field is a URL array and supports one or more links.

Field	Type	Required	Description
privacy_policy_link	string[]	No	Privacy policy URL(s). Displayed on the App Center detail page.
license_agreement_link	string[]	No*	License agreement URL(s). Terms of use or service agreement. * Required when the application uses open-source code.
source_code_link	string[]	No*	Source code URL(s). Repository or download location for source code. * Required when the application uses open-source code.
technical_support_link	string[]	No	Technical support URL(s). Support portal, ticket submission, or FAQ entry.

Open-Source Compliance Requirement

If your application uses open-source code (including direct use, modification, or redistribution of open-source components), you must configure both license_agreement_link and source_code_link to disclose the applicable license and how users can obtain the source code.

Example:

yaml

privacy_policy_link:
  - https://mycompany.example.com/privacy
license_agreement_link:
  - https://mycompany.example.com/license
source_code_link:
  - https://github.com/mycompany/myapp
technical_support_link:
  - https://mycompany.example.com/support

Permission Configuration

Field	Type	Required	Description
permissions	string[]	No	List of system permissions required by the application.

Supported Permission Types

Permission Identifier	Description	Minimum `depend_fw_version`
SYSTEM.EXEC_SYSTEM_COMMAND	Execute system commands. Allows execution of built-in commands in the system's `/usr/bin` and `/usr/sbin` directories	`1.13.0.0000`
NETWORK.ACCESS_INTERNET	Access network. Allows creating network connections to communicate with external internet services	`1.13.0.0000`
STORAGE.ACCESS_EXTERNAL	Access external storage. Allows access to mounted USB and external storage volumes	`1.17.0.0000`

When declaring permissions, you must set depend_fw_version in project.yaml, and its value must not be lower than the minimum firmware version required by each declared permission. If multiple permissions are declared, use the highest required version.

Application Custom Configuration (parameters)

The parameters field defines custom configuration items for the application, allowing users to configure them during installation or in the application configuration page of "Control Panel".

Configuration Item Structure

Field	Type	Required	Description
key	string	Yes	Configuration item identifier, used to reference the configuration in the application
type	string	Yes	Configuration item type. Valid values: - `string`: String - `number`: Number - `path`: Path - `password`: Password
required	boolean	No	Whether the field is required. Default: `false`
changeable	boolean	No	Whether the configuration can be modified after installation. Default: `false`
multi	boolean	No	Whether multiple values are supported. Default: `false`
i18n	object	Yes	Multilingual display information for the configuration item. See details below

Configuration Item Localization (parameters[].i18n)

Field	Type	Required	Description
name	string	Yes	Configuration item name
description	string	Yes	Configuration item description (additional notes, input guidelines, etc.)

Application Display Information Localization (i18n)

The i18n field defines display information for the application, including name, description, and various links.

Field	Type	Required	Description
name	string	Yes	Application display name
description	string	Yes	Application description
author	string	Yes	Application developer
official	string	No	Application official website URL
help	string	No	Help documentation URL, displayed on the application detail page
publisher	string	No	Application publisher
publisher_link	string	No	Publisher official website URL

Language Configuration and Fallback Rules

The system supports the following locale codes. At least one language must be configured in i18n

text

en-US
zh-CN
de-DE
ja-JP
fr-FR
nl-NL
pt-PT
es-ES
it-IT
ko-KR
zh-TW

Display rules:

Developers are responsible for ensuring the application works correctly when opened in unsupported language environments, including under the fallback language.
When listing in specific countries/regions only: besides adapting to the target locale, English must be provided as the fallback language. When users switch system language, if no matching locale is configured, English is used for all application detail and i18n display content.

Compatibility Notice

Internationalization of the application UI itself is the developer's responsibility. The i18n field in project.yaml only controls App Center detail page content; language compatibility after the application opens is handled by the developer.

Complete Configuration Example (project.yaml)

yaml

# Configuration specification version
spec_version: 2.1
# Application ID
app_id: com.mycompany.myapp
# Application version
version: 0.1.0
# Supported CPU architectures
support_arch:
  - amd64
  - arm64
# Supported client types (optional; defaults to app, pc when omitted)
supports:
  - app
  - pc
# Startup command
start_cmd: bin/myapp_serv --port=21010
# Service port
port: 21010
# Proxy path prefix
proxy_path: api
# Open type
open_type: inner
# Application categories
tag_types:
  - utility
  - devtool
# Minimum firmware version (required when permissions are declared and must meet permission requirements; contact UGREEN developers to confirm)
depend_fw_version: 1.13.0.0000
# Support migration
support_migration: true
# Allow users to authorize access to personal folders and shared folders
allow_add_access_path: true
# Compliance and support links
privacy_policy_link:
  - https://mycompany.example.com/privacy
license_agreement_link:
  - https://mycompany.example.com/license
source_code_link:
  - https://github.com/mycompany/myapp
technical_support_link:
  - https://mycompany.example.com/support
# Permission declarations
permissions:
  - SYSTEM.EXEC_SYSTEM_COMMAND
  - NETWORK.ACCESS_INTERNET
# Custom parameters
parameters:
  - key: ACCOUNT
    type: string
    required: true
    changeable: true
    i18n:
      en-US:
        name: Login Account
        description: 6-8 characters
      zh-CN:
        name: 登录账号
        description: 长度6-8位
# Localization information (keep en-US as the base language)
i18n:
  en-US:
    name: My APP
    description: My APP Description
    author: My Company
    official: https://myapp.example.com
    help: https://myapp.example.com/help
    publisher: My Company
    publisher_link: https://mycompany.example.com
  zh-CN:
    name: 我的应用
    description: 应用描述
    author: 演示应用开发者
    official: https://myapp.example.com.cn
    help: https://myapp.example.com.cn/help
    publisher: 演示应用发布者
    publisher_link: https://mycompany.example.com.cn

Development

Project configuration

System capabilities

JS-SDK

ugos-core

Sample projects

project.yaml Configuration Reference

Basic Configuration

Version Number Rules

Runtime Configuration

Application Dependencies

Docker Application Dependency

Feature Configuration

Application Links and Compliance Information

Permission Configuration

Supported Permission Types

Application Custom Configuration (parameters)

Configuration Item Structure

Configuration Item Localization (parameters[].i18n)

Application Display Information Localization (i18n)

Language Configuration and Fallback Rules

Complete Configuration Example (project.yaml)

ugos-core

project.yaml Configuration Reference ​

Basic Configuration ​

Version Number Rules ​

Runtime Configuration ​

Application Dependencies ​

Docker Application Dependency ​

Feature Configuration ​

Application Links and Compliance Information ​

Permission Configuration ​

Supported Permission Types ​

Application Custom Configuration (parameters) ​

Configuration Item Structure ​

Configuration Item Localization (parameters[].i18n) ​

Application Display Information Localization (i18n) ​

Language Configuration and Fallback Rules ​

Complete Configuration Example (project.yaml) ​

project.yaml Configuration Reference

Basic Configuration

Version Number Rules

Runtime Configuration

Application Dependencies

Docker Application Dependency

Feature Configuration

Application Links and Compliance Information

Permission Configuration

Supported Permission Types

Application Custom Configuration (parameters)

Configuration Item Structure

Configuration Item Localization (parameters[].i18n)

Application Display Information Localization (i18n)

Language Configuration and Fallback Rules

Complete Configuration Example (project.yaml)