Your First Workflow

Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-12 ｜ Source: chengflow-ui/src/features/editor, deploy/workflow-templates/, crates/cheng-nodes/src/nodes/builtin

This walks through building and running a workflow from an empty canvas. It takes about ten minutes and produces something small but genuinely useful: a workflow that takes text in, sends it to a language model, and shows you the result. You need a running installation — see Install ChengOS if you do not have one yet.

The vocabulary

Four terms carry most of the meaning, and they map exactly onto what you see on screen:

• A workflow is a directed graph. It is the unit you save, version, run, and publish.
• A node is one step. Each node declares typed inputs and outputs, and its configuration form is generated from a JSON Schema the backend publishes — which is why every node's property panel looks consistent without anyone hand-writing those forms.
• An edge connects one node's output port to another's input port. Edges carry data, and they are what defines execution order.
• An execution is one run of a workflow. It has its own record, its own state machine (pending → running → completed / failed / cancelled), and a trace you can inspect afterwards.

Nodes are addressed as category/name — io/input_text, ai/llm, utils/preview. You will see these identifiers throughout the documentation, and they are the same identifiers the API uses.

Step 1 — Open the editor

Go to http://<your-host>:8080 and sign in. On a brand-new installation no users exist yet, so you will be sent to first-run setup instead; the account you create there becomes the administrator.

Create a new workflow from the editor. You get an empty canvas with the node palette on the left, the canvas in the middle, and the property panel on the right.

Step 2 — Add an input node

Find io/input_text in the palette and drag it onto the canvas. This node is where your workflow receives text.

Click it to select it. The property panel on the right now shows its configuration. Give the field a name you will recognise later — something like user_input — and optionally a default value so you have something to test with.

Step 3 — Add a model node

Drag ai/llm onto the canvas, to the right of your input node.

Select it and configure the model in the property panel: pick a provider and model, and write a prompt. To reference the text coming from the previous node, use a variable reference rather than typing a literal — that is what wires the two steps together. For example:

Summarize the following in one sentence:

{{user_input}}

If no providers are configured yet, set one up under settings first. Credentials are stored in the encrypted vault, never inline in the node — the model node holds a reference, and the actual key is injected server-side at request time. This is deliberate: it means the language model never sees your API keys, even when an agent is deciding what to call.

Step 4 — Connect the nodes

Drag from the output port on the right edge of io/input_text to the input port on the left edge of ai/llm. A line appears connecting them.

Connections are type-checked. If a port refuses to connect, the two ports carry incompatible types — the editor is preventing a run that would fail partway through, rather than letting you discover the mismatch at execution time.

Step 5 — See the output

Drag utils/preview onto the canvas and connect the ai/llm output to it. Preview nodes exist purely to show you a value during development, which makes them the fastest way to understand what a node actually emits.

Your graph now reads: io/input_text → ai/llm → utils/preview.

Step 6 — Save and run

Save the workflow — the toolbar button, or Ctrl+S. First save prompts for a name; workflows are persisted in PostgreSQL, not in your browser.

Now run it. The execution view streams events over WebSocket as they happen, so you watch nodes light up in order rather than waiting for a final result: each node shows running, then completed or failed, and the preview node fills in when its input arrives.

If a node fails, click it. The execution detail shows the error for that specific node along with the inputs it actually received, which is almost always enough to identify the problem. The most common first-run failure is model configuration — a missing credential or a model name the provider does not recognise.

What to explore next

Start from a template. Every new workspace is bootstrapped with a set of built-in workflow templates, and reading a working workflow teaches more than building a trivial one:

Then: turn a workflow into a chat interface, give an agent tools so it can decide what to call, or publish a workflow as an app with its own pages.

Next steps

• Publish it as an app — give it a URL other people can use.
• REST API overview — run the same workflow from code.
• Environment variable reference — enable agent memory and vector retrieval.