ArcFlow documentation
ArcFlow is a self-hosted AI workflow runtime written in Rust. One engine (arcflow-core) powers Python and TypeScript SDKs, the HTTP server, Relay, and the static browser SDK. Workflows are defined as versioned JSON specifications: agents, steps, optional graph routing, tools, vector memory, human-in-the-loop gates, and external callbacks.
This site helps you build workflows in code, integrate via HTTP, or ship a static-site chat widget. For wire-format basics see Workflow specification and Trace events (normative).
Three entry paths
Build workflows in code. Start with First workflow in five minutes or the Getting started curriculum. Read What is ArcFlow? and Execution model when you need graph routing or HITL.
Integrate via HTTP. Start with Server API quickstart. Pair with Architecture overview and Surfaces and when to use them (Postgres is required for server runs).
Ship a static-site chatbot. Start with Static site chatbot lesson or Static product overview. Relay keeps LLM keys off the browser. See Trace data policy for trace rules.
Which surface should I use?
| Surface | Primary use | Postgres required |
|---|---|---|
| Python / TypeScript SDK | Scripts, notebooks, backend services | Only when recovery or registry is enabled |
| arcflow-server | HTTP API, registry, persistence | Yes for POST /v1/runs |
| arcflow-relay | Browser proxy, origin check, rate limit | No |
| arcflow-static | Browser runPublished() | No (calls Relay or server) |
| arcflow CLI | Local run, trace | For migrate only |
| VS Code extension | Authoring, debug, graph view | No |
| Scenario | Recommended surface |
|---|---|
| Internal batch job | Python or TypeScript SDK embedded |
| Multi-tenant SaaS backend | arcflow-server plus your auth layer |
| Public website chat widget | Relay + static SDK + admin publish |
| Local debugging | SDK or CLI, optional VS Code |
See Surfaces and when to use them for the full comparison.
ArcFlow services
Use this table to jump to the docs for the component you run or integrate against.
| Service | You use it when… | Start here | Deploy | Security |
|---|---|---|---|---|
| Python / TypeScript SDK | Workflows run inside your app or notebook | Python quickstart · TypeScript quickstart | Install and build | Trace data policy |
| arcflow-server | Backends call HTTP APIs, need Postgres-backed runs and registry | Server overview · Server API quickstart | Server deployment · Docker Compose | Authentication · API key management |
| arcflow-relay | Browsers call workflows without LLM keys in the bundle | Relay overview · Request path | Relay deployment · BYO relay | Relay security model |
| Static product | Published chat widgets, site knowledge, admin publish flow | Static product overview · Static site chatbot | Deployment overview · Production checklist | Static product security |
| CLI / VS Code | Local runs, traces, workflow authoring | CLI overview · VS Code overview | , | , |
Hosting stack (typical): Postgres + arcflow-server (+ optional arcflow-relay for public sites). See Deployment overview, Environment variables, and Health and readiness.
HTTP integrators: HTTP API reference, Idempotency, Run state machine, Error codes.
Concepts worth reading early
| Topic | Page |
|---|---|
| Personas and non-goals | What is ArcFlow? |
| Layers and integration flows | Architecture overview |
| Workflow JSON, specification-first design | Workflow specification |
| Linear vs graph, run states | Execution model |
| Trace metadata rules | Trace data policy |
| Production vs deferred features | Maturity and known gaps |
Site map
| Section | Purpose |
|---|---|
| concepts/ | Architecture, workflow specification, execution, maturity |
| getting-started/ | Curriculum: install, lessons, outcome paths |
| guides/ | Task-oriented how-to guides |
| sdks/ | Python and TypeScript SDK reference |
| server/ | HTTP server and persistence |
| relay/ | Browser-facing proxy |
| static-product/ | Sites, knowledge, published workflows |
| deployment/ | Docker and production |
| security/ | Auth, webhooks, self-hosted hardening |
| tutorials/ | Tracks A through H |
| certification/ | Self-assessed competency levels |