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 number 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
support_arch	string[]	Yes	List of supported CPU architectures. Valid values: amd64, arm64
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

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
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	Yes	Minimum required UGOS Pro system version. Example: 1.13.0.0000

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

Permission Configuration

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

Supported Permission Types

Permission Identifier	Description
SYSTEM.EXEC_SYSTEM_COMMAND	Execute system commands. Allows execution of built-in commands in the system's /usr/bin and /usr/sbin directories
NETWORK.ACCESS_INTERNET	Access network. Allows creating network connections to communicate with external internet services

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.

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
publisher	string	No	Application publisher
publisher_link	string	No	Publisher official website URL

Supported languages:

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

Complete Configuration Example (project.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
# 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
# Required system version
depend_fw_version: 1.12.0.0000
# Support migration
support_migration: true
# Allow users to authorize access to personal folders and shared folders
allow_add_access_path: true
# 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
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