Installing ChengOS

Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: deploy/README.md, deploy/chengos.sh, deploy/.env.example, deploy/lib/doctor.sh

ChengOS installs from a single management script, chengos.sh, which handles both supported deployment modes. This page covers the fastest path to a running system on one machine. If you already know you want containers, skip to Docker deployment.

Only want to try ChengFlow on your own computer, with no server? The release page also carries ChengFlow Desktop installers for Windows (.msi) and Linux (.deb), which bundle the editor, the engine, and a database in one app.

Before you start

You need a 64-bit Linux host with at least 4 GB of RAM and 10 GB of free disk. Everything else depends on which mode you pick:

Mode	What it needs	Best for
Native (hybrid)	Nothing but the release archive. Databases run as unprivileged user processes.	Trying ChengOS out, single-machine installs, hosts where you have no root
Docker	Docker Engine and the Compose plugin	Production, reproducible installs, hosts where you want everything contained

Native mode is the lighter of the two: it runs the compiled cheng-api binary directly on the host and serves the web assets from the same package, so there is no image pull and no container runtime to manage.

Install in native mode

From the deploy/ directory (the script also works from the repository root):

./chengos.sh install --mode native --db-install-mode managed-process --with api,ui,app,cli
./chengos.sh start
./chengos.sh status

That is the whole installation. The three flags are worth understanding:

--mode native runs the API binary and static assets on the host, without Docker.
--db-install-mode managed-process starts PostgreSQL, Valkey, and Qdrant as ordinary user processes inside the installation directory. No root or sudo is required. The alternative, --db-install-mode system-service, installs the databases through apt-get and registers them as systemd units, which does need sudo.
--with api,ui,app,cli selects the modules to install. Drop any you do not want — for example --with api,ui skips the chat gateway and the terminal client.

Run ./chengos.sh with no arguments instead to get an interactive bilingual menu covering the same operations plus update, rollback, and uninstall.

What you get

Once chengos.sh start reports success, four services are listening:

Service	Default port	Purpose
API backend (`cheng-api`)	`19225`	REST API and WebSocket streams; everything else talks to this. Listens on `127.0.0.1` only.
Main UI (`cheng-ui`)	`8080`	The visual workflow editor and admin console
Chat app (`cheng-app`)	`5055`	Chat client and mobile H5 interface
PostgreSQL	`5432`	Primary datastore

Valkey (6379) and Qdrant (6333/6334) are installed but disabled by default in native mode — see ENABLE_REDIS and ENABLE_QDRANT in the environment reference. Turn them on when you start using agent memory or RAG retrieval.

Open http://<your-host>:8080 in a browser. On a fresh database no users exist yet, so the UI sends you to first-run setup and the account you create there becomes the administrator.

Create the `cheng` and `chengos` shortcuts

The installer can symlink two launchers into /usr/local/bin so they work from any directory. Choose Install Command Shortcuts from the interactive menu, then:

chengos opens the management console menu from any terminal.
cheng starts the CLI chat client from any terminal.

Installing only the CLI

To drive an existing ChengOS server from a laptop or a different machine, install just the terminal client:

./chengos.sh cli

The wizard asks whether this is a local or a remote install. Local installs auto-connect to http://127.0.0.1:19225. Remote installs prompt for the server URL — for example https://your-server.example.com — and store it as CHENG_SERVER_URL. Then run cheng from any terminal to start chatting.

Pin your version before going to production

A first install defaults to CHENGOS_VERSION=latest in deploy/.env. That is a convenience for evaluation only. latest is a moving pointer, which makes an installation non-reproducible and makes rollback ambiguous, because there is no single release to roll back to.

Before you rely on an installation, edit deploy/.env and pin the exact release:

CHENGOS_VERSION=0.2.0

chengos.sh update rewrites this value for you, but only after the target release has been verified, and it records the previous value so chengos.sh rollback can restore it.

Verify the installation

# The API answers health checks
curl http://127.0.0.1:19225/health

# Processes, ports, and recent log output
./chengos.sh status

A healthy system responds to /health and shows every selected module running under status. If it does not, check deploy/logs/ first — startup failures are almost always a database connection problem or a port already in use.

Then run the read-only exposure check:

./chengos.sh doctor

It probes what the running system actually listens on and serves — listen addresses, proxy trust, CORS, security headers — and exits non-zero on a problem. The API binds to 127.0.0.1 by default, but the UI and app servers listen on every interface until you change UI_BIND and APP_BIND. Before exposing the host to the internet, follow Hardening a Public Deployment.

Next steps

Build your first workflow in the editor.
Configure environment variables, especially the secrets that a production install must not leave at their defaults.
Deploy with Docker if you want a containerized installation.
Harden a public deployment before opening it to the internet.