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

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:

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:

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:

./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

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

Once started, four services are listening:

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:

Next Steps

• Publish a workflow as an app — give it a URL others can access
• REST API overview — call the same workflow from code
• Environment variable 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.