Frequently Asked Questions

Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-13 ｜ Source: root README.md, deploy/README.md, deploy/.env.example, deploy/config/providers.toml, crates/cheng-core/src/types.rs

Short answers to the questions that come up most, each pointing at the page with the detail.

Getting started

What is ChengOS, in one sentence? A visual, node-based workflow system for AI-powered data processing: you draw a graph, it runs as a DAG, and you can publish the result as an app, a chat channel, or an API. See What ChengOS Is.

What do I actually need to run it? PostgreSQL. That is the only hard requirement. Redis is needed for scheduling and agent memory, Qdrant for RAG, and both default to off. See Deployment Modes.

Native or Docker? Native to try it, Docker to run it. Native with DB_INSTALL_MODE=managed-process installs with no root at all. See Native Deployment and Docker Deployment.

How long until something works? About ten minutes for your first workflow; fifteen more for your first agent.

Workflows

Workflow, node, edge, execution — what is the difference? A workflow is the graph you save and version. A node is one step with typed inputs and outputs. An edge connects an output port to an input port and defines order. An execution is one run, with its own record and trace. See Core Concepts.

Why is my node's field not editable? Because an edge is connected to it. Edges beat configuration in the input precedence order.

Why did my node get skipped? A node whose incoming edges all produce null is auto-skipped. That is how conditional routing works — the unselected branch receives null and skips itself, cascading downstream.

Can I keep workflows in Git? Yes. Export workflow.json; identity and tenancy are never read from the file, so it is safe to commit, review, and diff. See Workflow Versioning.

Is there a version history I can roll back to in the editor? No. The version counter and change_note are metadata, not snapshots. Git is the answer.

Subflow or loop container? Subflow when the callee is a reusable workflow with its own identity; loop container when you just need the same local nodes run per item. See Subflows & Batch Subflows.

Agents

My agent does nothing / replies without calling tools. The provider probably does not declare native_tool_calling. Anthropic and Ollama do not, in the shipped providers.toml. See LLM Provider Errors.

Agent or plain graph? Agent when the steps genuinely depend on what earlier steps find; graph when you already know the sequence, because a graph is cheaper, faster, and predictable.

How do I stop it running forever? max_iterations bounds it, and task_run_mode: short (the default) pauses and asks you rather than stopping silently. long mode renews the budget only while the agent is making progress. See ReAct Agent Guide.

How do I stop it doing something dangerous? An approval gate before the action, or simply not enabling the capability — hub nodes default their write switches to off, and an off switch fails before the operation runs.

Tool, skill, or MCP server? A tool is one callable function. A skill packages a capability with instructions and schemas. An MCP server is external capability provided by another process.

Data

Document or table? Documents are a block tree for prose, with per-block priority and tags. Tables are typed columns and stable record ids. Both are safe to hand to a model, for different reasons.

How do I let an agent edit a document safely? It already is safe: writes go through a shadow session, staged and reviewable per block, and the execution waits for a decision.

Do I need Qdrant for everything? Only for RAG. Documents, tables, and knowledge base records live in PostgreSQL.

Which retrieval mode should I use? Start with economy. Move to power when recall is the problem. Use ultimate only after measuring that reranking earns its latency.

Execution

How many states does an execution have? Eight: pending, running, paused, waiting_for_review, completed, failed, cancelled, timeout. The last four are terminal.

Why is my execution stuck in waiting_for_review? It is waiting for an approval or a review decision. If the approval card's buttons return NO_ACTIVE_APPROVAL_WAITER, the waiter is gone and the reaper will time it out — see Approvals & Human Review.

Does retrying overwrite the failed run? No. A retry produces a new execution id; the failed run stays intact as evidence.

How long are traces kept? Per workspace, with separate day counts for completed and failed executions, plus archive retention classes. See Traces, Logs & Replay.

Integration

Can I run a workflow from my own code? Yes — the REST API, with the WebSocket API for live events.

Generated client or the SDK? The SDK for chat and gateway work: it also handles the WebSocket protocol, session mapping, and token refresh, which an OpenAPI generator cannot produce.

How do I put this in WhatsApp or Slack? Create a channel, bind a workflow, connect. Telegram, Slack Socket Mode, and DingTalk need no public URL. See Messaging Channels.

Does channelId choose the workflow? No. The workflow is bound explicitly on the channel record. channelId says which app the message came from. See Channel Routing.

Operations

What must I back up? The database and CREDENTIAL_MASTER_KEY_1. Lose the key and every stored credential is unrecoverable — a database backup alone will not restore a working system.

Why does the frontend build fail? pnpm build runs gen:pages, which calls the backend to render pages. Start the backend first. See Development Setup.

Why does git status show m chengflow-sdk? chengflow-sdk is recorded as a bare gitlink with no .gitmodules. It is expected, not a dirty worktree.

Is the OpenAPI spec complete? No — it documents 28 paths, a curated subset. rest/routes.rs and the REST overview are authoritative.

Can I run the CLI against a remote server and keep my files local? Yes, that is workspace_mode: client_local, which is the automatic default for any non-local server URL. See Remote & Cross-Device Connections.

Extending

How do I add a node? A struct, #[derive(Node)], typed input and output, one function, and a registration macro with a sandbox capability — an unclassified node is UnsupportedForCli. See Writing a Custom Node.

Do I have to write frontend code for it? No. The property panel is generated from the node's JSON Schema.

Where do I put shared configuration? Global presets.yaml / shortcuts.yaml, with per-workspace files only for genuine overrides. See Presets & Shortcuts.

Next steps