# 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](/docs/what-is-chengos).

**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](/docs/deploy-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](/docs/deploy-native) and
[Docker Deployment](/docs/deploy-docker).

**How long until something works?**
About ten minutes for [your first workflow](/docs/quickstart-first-workflow); fifteen more for
[your first agent](/docs/quickstart-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](/docs/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](/docs/editor-variables-and-mapping).

**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](/docs/editor-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](/docs/editor-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](/docs/fix-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](/docs/agent-react-guide).

**How do I stop it doing something dangerous?**
An [approval gate](/docs/exec-approvals-reviews) 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](/docs/agent-skills-system) packages a capability with
instructions and schemas. An [MCP server](/docs/agent-mcp-integration) 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](/docs/data-document-workspace), staged
and reviewable per block, and the execution waits for a decision.

**Do I need Qdrant for everything?**
Only for [RAG](/docs/data-rag-pipeline). 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](/docs/exec-approvals-reviews).

**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](/docs/exec-traces-logs).

## Integration

**Can I run a workflow from my own code?**
Yes — the [REST API](/docs/api-rest-overview), with the
[WebSocket API](/docs/api-websocket) for live events.

**Generated client or the SDK?**
The [SDK](/docs/sdk-api-reference) 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](/docs/chat-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](/docs/chat-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](/docs/dev-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](/docs/api-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](/docs/cli-remote-connect).

## 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](/docs/dev-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](/docs/config-presets).

## Next steps

- [Installation Problems](/docs/fix-install-issues) — when setup goes wrong.
- [Execution Failures](/docs/fix-execution-failures) — when a run goes wrong.
- [System Overview](/docs/system-overview) — how the pieces fit.