chengos.sh Script Reference

Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-14 ｜ Source: deploy/chengos.sh, deploy/lib/release-update.sh

chengos.sh is the single entry point for installing, operating, updating, and uninstalling ChengOS. It runs as an interactive menu with no arguments, or as a non-interactive CLI with a command verb. This page is a complete reference for every command, flag, and mode it supports.

Bootstrap mode

When the script is run on a machine that does not already contain a ChengOS installation (no start.sh, no hybrid/, no deploy/), it acts as a bootstrap installer:

curl -fsSL https://raw.githubusercontent.com/chengrouter/chengos/main/deploy/chengos.sh | bash

The bootstrap will:

Ask for an installation directory (default ./chengos).
Look for a local release tarball in the current directory.
If none is found, download the latest release from GitHub.
Extract the package and re-launch chengos.sh in local mode.

You can also place a release tarball next to the script before running it — the bootstrap detects chengos-full-linux-amd64*.tar.gz and uses it instead of downloading.

Interactive menu

Running chengos.sh with no arguments launches a bilingual (Chinese / English) interactive menu:

./chengos.sh

Option	Action
1	Install / Initialise Modules
2	Start Services
3	Stop Services (optionally stop databases too)
4	Restart Services
5	Update Modules (scripts, package, or both; force; low-disk)
6	Install CLI Only (local or remote)
7	Service Status (process, port, CLI status)
8	Install Command Shortcuts (`chengos` and `cheng` symlinks)
9	Uninstall / Stop Modules
10	Switch Language
11	Exit
12	Reset Login Credentials
13	Roll Back to Previous Version

Language preference is stored in .chengos_lang and remembered across runs.

Commands

All commands can be run non-interactively by passing the command verb as the first argument.

install

./chengos.sh install --mode native --with api,ui,app,cli --db-install-mode managed-process \
    --ui-port 8080 --app-port 5055

Flag	Default	Description
`--mode`	auto-detected	`native` or `docker`
`--with`	`api,ui,app,pg,redis,qdrant`	Comma-separated module list
`--db-install-mode`	`managed-process`	`managed-process` (no root) or `system-service` (sudo)
`--ui-port`	8080	UI server port
`--app-port`	5055	Chat app port
`--workspace-root`	`./workspaces`	Workspace storage path

Modules: api, ui, app, cli, redis (Valkey), qdrant, pg (PostgreSQL).

When chengflow/ and chengflow-ui/ source directories exist, the installer compiles from source instead of extracting a release archive.

start

./chengos.sh start --mode native

Starts all recorded modules. The module set is read from .chengos_modules (written during install) so you do not need to repeat --with.

stop

./chengos.sh stop --mode native
./chengos.sh stop --mode native --with-infra

--with-infra also stops database services (PostgreSQL, Valkey, Qdrant).

restart

./chengos.sh restart --mode native

Stops then starts with the recorded module set.

status

./chengos.sh status --mode native

Prints installed version, latest available release, process PIDs, and port status. Exits non-zero when the API is not serving — usable as a health probe in monitoring scripts.

version

./chengos.sh version

Prints the bare installed version string (or unknown). Designed for scripting.

update

./chengos.sh update                          # scripts + package (recommended)
./chengos.sh update --scripts-only           # scripts only
./chengos.sh update --package-only           # package only (binaries, frontends, config)
./chengos.sh update --force                  # force package update, skip version check
./chengos.sh update --low                    # low-disk mode (see below)
./chengos.sh update --to v0.2.0              # target a specific release
./chengos.sh update --package-only --force   # force package reinstall
./chengos.sh update --package-only --low     # low-disk package-only update

Flag	Description
`--scripts-only`	Update only `chengos.sh`, `start.sh`, `stop.sh`, `status.sh`, `generate-env.sh`
`--package-only`	Update only the release package (binaries, frontends, config, skills, templates)
`--force`	Skip the version check; reinstall or downgrade deliberately
`--low`	Low-disk mode: sequential operation to minimise peak disk usage (see below)
`--to <version>`	Target a specific release version instead of the latest

Updates are upgrade-only by default: remote > local must hold. Use --force to override.

The full update flow is described in Upgrades & Rollback.

rollback

./chengos.sh rollback --mode native

Restores the most recent backup in .chengos_backups/, restarts services, and runs a health check. The consumed backup is removed, so a second rollback walks one release further back.

install-cli

./chengos.sh install-cli --target local --server-url http://127.0.0.1:19225
./chengos.sh install-cli --target remote --server-url https://your-server.example.com

Installs the cheng CLI binary and writes a config file pointing at the specified API server.

reset-credentials

./chengos.sh reset-credentials
./chengos.sh reset-admin

Resets the login username, email, and/or password. Both aliases are equivalent.

uninstall

./chengos.sh uninstall --mode native

Stops all services and removes package-owned files. Database data is preserved unless you answer "yes" to the prompt about stopping databases.

Low-disk mode (`--low`)

When the installation filesystem has very little free space (e.g. 1 GB), the normal update flow can fail the space check because it needs room for the download, the extracted tree, the backup, and a staged copy — all at once.

--low restructures the update into a sequential pipeline that minimises peak disk usage:

Step	Normal mode	Low-disk mode
Space check	4× archive size (~260 MB)	2× archive size (~130 MB)
After extraction	Archive kept	Archive deleted immediately (~65 MB freed)
Before backup	Old backups kept (up to 3)	Old backups pruned to 1 (~400 MB freed)
File replacement	cp→staged, mv→retired, mv→staged→target	mv→retired, cp→target directly (no staged copy)
After install	Staging kept until function return	Staging cleaned before health check
Backup retention	Keep 3	Keep 1

Rollback safety is preserved: one backup is always kept, and a failed health check still triggers automatic restore.

./chengos.sh update --low                    # scripts + package, low-disk
./chengos.sh update --package-only --low     # package only, low-disk

Environment variables

These variables control the update and script behaviour. Set them in the shell or in .env.

Variable	Default	Description
`CHENGOS_BACKUP_KEEP`	3	Number of backups to retain after update
`CHENGOS_META_TIMEOUT`	10	Seconds for release metadata lookup
`CHENGOS_DOWNLOAD_TIMEOUT`	1800	Seconds for artifact download
`CHENGOS_HEALTH_TIMEOUT`	90	Seconds for post-update health check
`CHENGOS_REQUIRE_SIGNATURE`	auto	`auto`, `required`, or `off`
`CHENGOS_LOCAL_TARBALL`	—	Path to a local release tarball (overrides download)
`CHENGOS_UPDATE_BRANCH`	main	GitHub branch for script-only updates
`CHENGOS_RAW_BASE_URL`	derived from branch	Base URL for raw script downloads

Files and metadata

File	Purpose
`.chengos_lang`	Language preference (`zh` or `en`)
`.chengos_install_mode`	Installation mode (`native` or `docker`)
`.chengos_version`	Installed release version
`.chengos_modules`	Comma-separated list of installed modules
`.chengos_cli_target`	CLI installation target path
`.chengos_docker_version`	Docker image version pin
`.chengos_backups/`	Versioned backup directories

Command shortcuts

Option 8 in the menu (or manual setup) creates two symlinks in /usr/local/bin:

chengos → launches the management menu from any terminal.
cheng → launches the CLI chat client with file-based credential storage.

Next steps

Native Deployment — day-to-day operations in native mode.
Upgrades & Rollback — the update flow in detail.
Deployment Modes — native vs Docker vs distributed.
Environment Variable Reference — every .env variable.