# 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](/docs/deploy-docker).

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):

```bash
./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](/docs/config-env-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:

```bash
./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:

```bash
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

```bash
# 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:

```bash
./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](/docs/deploy-hardening).

## Next steps

- [Build your first workflow](/docs/quickstart-first-workflow) in the editor.
- [Configure environment variables](/docs/config-env-reference), especially the secrets
  that a production install must not leave at their defaults.
- [Deploy with Docker](/docs/deploy-docker) if you want a containerized installation.
- [Harden a public deployment](/docs/deploy-hardening) before opening it to the internet.