# From Zero to Your First Workflow: Getting Started with ChengOS in 10 Minutes

This tutorial walks you from a blank Linux server all the way to **running your first AI workflow**. It takes about 10 minutes, and the result is small but genuinely useful: a workflow that takes text, sends it to an LLM, and displays the result.

> Full documentation: [Installation Guide](/docs/install-chengos) and [Your First Workflow](/docs/quickstart-first-workflow). This post is a beginner-friendly walkthrough that adds practical details not covered in the docs.

## Minute 0: What You Need

- A 64-bit Linux host
- An LLM API key (OpenAI / Claude / DeepSeek / a local Ollama model all work)

**Hardware requirements (real-world measurements):**

| Tier | Spec | Notes |
|---|---|---|
| **Standard** | 2 vCPU / 4 GB RAM / 10 GB disk | Recommended; comfortable for Docker mode too |
| **Low** | 1 vCPU / 1 GB RAM | Runs fine in binary mode |
| **Minimum** | 1 vCPU / **512 MB RAM** | Still runs smoothly — requires the **binary version**, with no Docker or other memory-hungry programs on the host |

Measured memory usage:

- **Binary (Native) mode**: all ChengOS components together use **under 150 MB**; total including the OS stays **under 300 MB**
- **Docker mode**: with extra image overhead, total memory usage stays **under 600 MB**

ChengOS offers two deployment modes:

| Mode | Dependencies | Best for |
|---|---|---|
| **Native** | Just the release package; databases run as regular user processes | Trials, single machines, hosts without root, low-memory VPS |
| **Docker** | Docker Engine + Compose plugin | Production, reproducible deployments |

For beginners we recommend **Native mode** — no root, no images to pull, the lightest option. Even a 512 MB machine can run it.

## Minute 1: Installation

**Recommended for beginners: interactive install** — one command gets you into a guided setup:

```bash
curl -fsSL https://chengos.dev/chengos.sh | bash
```

This opens a **bilingual interactive menu**:

```
===========================================
       ChengOS Unified Management & Deployment Tool
===========================================
  1) Install/Init modules (Install/Init)
  2) Start services (Start)
  3) Stop services (Stop)
  4) Restart services (Restart)
  5) Update modules (Update)
  6) Install CLI only (Install CLI Only)
  7) View service status (Status)
  8) Install command shortcuts (Install Command Shortcuts)
  9) Uninstall/disable modules (Uninstall)
  10) Switch language (Switch Language)
  11) Exit (Exit)
  12) Reset login username/password (Reset Credentials)
  13) Roll back to previous version (Rollback)
===========================================
Select an action [1-12]:
```

Pick `1` to enter the install wizard, choose your mode and modules as prompted, then `2` to start and `7` to check status. Install, update, rollback, credential reset, and uninstall all live in this single menu — users uncomfortable with CLI flags never need to open the docs.

If you prefer scripted/CI deployments, use the flag-through mode from the `deploy/` directory:

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

A quick explanation of the three flags (understand them and you can trim as needed):

- `--mode native`: runs the API binary and static assets directly on the host, no Docker
- `--db-install-mode managed-process`: PostgreSQL, Valkey, and Qdrant run as **regular user processes** inside the install directory — **no sudo required** (the alternative `system-service` mode uses apt + systemd and needs root)
- `--with api,ui,app,cli`: which modules to install; if you only want the editor, `--with api,ui` is enough

## Minute 2: Verify the Installation

```bash
curl http://127.0.0.1:3000/health   # API health check
./chengos.sh status                # processes, ports, logs
```

Once started, four services are listening:

| Service | Port | Purpose |
|---|---|---|
| API backend | `3000` | REST API + WebSocket |
| Main UI | `8080` | Visual workflow editor |
| Chat app | `5055` | Chat client / mobile H5 |
| PostgreSQL | `5432` | Primary data store |

Open `http://<your-host>:8080` in a browser. A fresh database has no users, so you'll land in **first-run setup** — the account you create here is the admin.

> ⚠️ If it won't start, check `deploy/logs/` first. Nine times out of ten it's a database connection issue or an occupied port.

## Minutes 3–8: Build Your First Workflow

### Four terms to know

- **workflow**: a directed graph — the unit of saving, versioning, running, and publishing
- **node**: one step, with typed inputs and outputs. Nodes are addressed as `category/name`, e.g. `io/input_text`, `ai/llm`
- **edge**: connects an upstream output port to a downstream input port; edges determine execution order
- **execution**: one run, with its own state machine (pending → running → completed / failed / cancelled) and a reviewable trace

### Step 1: Add an input node

Find `io/input_text` in the left node panel and **drag it onto the canvas**. Select it, give the field a name in the right properties panel — say `user_input` — and set a default value for testing.

### Step 2: Add a model node

Drag an `ai/llm` node to the right of the input node. In the properties panel, pick a provider and model, then write your prompt. **Reference upstream text with variable references**, don't paste literals — that's what actually connects the two steps:

```
Summarize the following in one sentence:

{{user_input}}
```

> 🔑 If you haven't configured a model provider yet, do that in settings first. Credentials live in an encrypted vault; nodes only hold references — **the real key is injected server-side at request time, and the LLM never sees it**.

### Step 3: Connect the nodes

Drag from `io/input_text`'s output port to `ai/llm`'s input port. Connections are **type-checked** — if you can't connect them, the port types are incompatible, and the editor is catching an error you'd otherwise only see at runtime.

### Step 4: Add a preview node

Drag in `utils/preview` and connect `ai/llm`'s output to it. Preview nodes exist to show intermediate values during development — the fastest way to understand what a node actually outputs.

Your graph is now: **`io/input_text` → `ai/llm` → `utils/preview`**

### Step 5: Save and run

`Ctrl+S` to save (you'll be asked to name it the first time; workflows are stored in PostgreSQL, not the browser). Then hit run — the execution view streams events in real time over WebSocket, so you watch nodes light up in order instead of waiting for a final result.

If a node fails, click it: the execution detail shows the error **and the input it actually received** — usually enough to pinpoint the problem. The most common first-run failure is model configuration: a missing credential or a typo'd model name.

## Minutes 9–10: Continue from Templates

Once it runs, don't reinvent the wheel — every new workspace ships with built-in templates, and **reading a working workflow teaches you faster than building a toy one**:

| Template | What it demonstrates |
|---|---|
| `no-memory-chat` | Minimal chat workflow: input straight to model, no history |
| `memory-chat` | Conversation memory: load history, windowing, persist replies |
| `tools-user` | ReAct agent with file tools, autonomous in a sandbox |
| `http-tools` | Give the model HTTP tools so it can call external APIs itself |
| `main-chat` | Intent routing: conditional dispatch to three sub-workflows |
| `scheduled-task` | Manage scheduled tasks in natural language |
| `skills-run` | Discover and run installed Skills |

## Next Steps

- [Publish a workflow as an app](/docs/app-publish-workflow) — give it a URL others can access
- [REST API overview](/docs/api-rest-overview) — call the same workflow from code
- [Environment variable reference](/docs/config-env-reference) — enable agent memory and vector retrieval

---

**Check-in time:** If you got your first workflow running, reply with a screenshot of your three-node graph and the model output! Stuck somewhere? Just ask — we read every reply.