1flowbase

English | 简体中文

Community: WeChat | WeChat Official Account | Twitter

1flowbase is a self-hosted AI gateway for individuals and enterprises: on top of protocol translation, dispatch, and detailed chat logs, it ships with a built-in Application Backend and Native React frontend blocks that help you combine AI with your business data. Most importantly, all of it can be operated and managed by your Agent through MCP.

1flowbase lets an Agent take over the entire application through MCP — whether orchestrating and publishing an AI gateway, generating backend application endpoints, or building native React interfaces.

Local Agent        -> MCP Gateway         -> discover / configure / build / operate
Model clients      -> AI Gateway          -> compatible endpoints / model workflows / traces
External systems   -> Application Backend -> generated CRUD APIs / custom workflow APIs
People             -> React blocks        -> interactive application UI

The four foundations can be used independently, or combined around the same 1flowbase application.

Foundation	What it provides
AI Gateway	Translate and dispatch OpenAI Responses, Chat Completions, and Claude Messages traffic; route models and publish observable workflows as virtual models
MCP Gateway	Project 1flowbase capabilities into progressively discoverable tools; manage Tools, mappings, Groups, Bindings, policies, upstream MCP connections, and reusable Bundles
Application Backend	Define Data Models that materialize PostgreSQL tables, fields, indexes, and relations; automatically generate governed CRUD APIs and publish custom endpoints powered by Workflows
Native React frontend blocks	Build responsive application interfaces with standard React/TSX and CSS, controlled component imports, data binding, and Shadow DOM isolation

For example, a local Agent can create Customer and Ticket Data Models through MCP, assemble a workflow-backed /api/ex/tickets/escalate endpoint, and build the React interface. External systems call the generated backend APIs, while people work directly in the interface. If the same local Agent also points its model endpoint at the AI Gateway, it gains virtual models with routing, model composition, and full logs; the application itself does not depend on this optional connection.

---

What You Can Build

Let an agent build and operate a 1flowbase application

The MCP Gateway projects platform capabilities into an agent-oriented virtual UI. An agent can progressively discover the relevant domain, inspect a tool contract, make a call, verify the resulting state, and continue building — no hard-coded frontend flow needed for each new task.

Agent
  -> mcp_list: discover applications and capabilities
  -> mcp_get: inspect the next tool contract
  -> mcp_call: create, configure, run, and publish
  -> inspect state / traces
  -> iterate

Create a ready-to-use application backend

Define and publish a Data Model in 1flowbase, and the platform materializes the PostgreSQL schema and generates model-aware List, Get, Create, Update, and Delete APIs with OpenAPI contracts. When standard CRUD is not enough, use a Workflow Extension to define business logic and publish it as a custom endpoint under /api/ex/{slug}.

Data Model definition
  -> PostgreSQL table / columns / indexes / relations
  -> generated CRUD runtime APIs + OpenAPI

Workflow
  -> custom input/output contract
  -> published /api/ex/{slug} endpoint

Build the human interface with Native React blocks

Frontend blocks use standard React/TSX, Hooks, events, and CSS directly. 1flowbase compiles and mounts each block in an isolated Shadow DOM runtime, exposing the platform capabilities the block is allowed to use through controlled catalogs and context contracts.

export default function StatusCard({ ctx }) {
  const status = ctx.inputs.status;
  return <button onClick={() => ctx.outputs.publish({ action: 'retry' })}>
    {status}
  </button>;
}

Add vision to text-first coding models

Keep GLM-5.2, DeepSeek V4, or another strong text-based coding model in charge of planning and writing code, and let 1flowbase route screenshots, UI images, charts, and PDF pages to a mounted vision model.

Claude Code
  -> 1flowbase virtual model endpoint
  -> GLM-5.2 / DeepSeek / other main coding model
  -> mounted vision tool
  -> GLM-5V-Turbo / Gemini / GPT vision / OCR model
  -> structured visual result
  -> final coding answer

Guide: Make GLM-5.2 See Images in Claude Code with 1flowbase

Publish a Fusion-style multi-model reviewer

1flowbase ships with a fusion template. The client calls a single model name; 1flowbase queries multiple branch models in the background, invokes a synthesis model, returns the final answer, and keeps the execution record of every branch.

User request
  -> Main LLM
  -> fusion tool
     -> Branch LLM A
     -> Branch LLM B
     -> Branch LLM C
     -> Synthesis LLM
  -> final answer

Guide: Fusion-Style Workflows: Publish a Multi-Model Panel as an Observable Virtual Model

Publish workflow-backed model APIs

Build the workflow once, then serve it through common model protocols:

Protocol	API path	Typical usage
OpenAI Responses API	/v1/responses	newer OpenAI-style clients and application code
OpenAI Chat Completions API	/v1/chat/completions	SDKs, coding tools, chat clients, application frameworks
Claude-compatible Messages API	/v1/messages	Claude-compatible clients that support custom endpoints

---

Installation or Upgrade

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/taichuy/1flowbase/main/scripts/shell/docker-deploy.sh | sh

迁移到新机器时，运行同一官方命令会询问是否恢复一个便携备份；也可显式指定备份文件（如备份设置过密码，再加 --restore-password）：

curl -fsSL https://raw.githubusercontent.com/taichuy/1flowbase/main/scripts/shell/docker-deploy.sh | sh -s -- --restore-backup /safe/path/system.1fb-backup

恢复在首次启动前完成。请使用备份中原有的 root 登录凭据；脚本不会把新 .env 的初始密码误报为已恢复系统的密码。

Windows PowerShell:

irm https://raw.githubusercontent.com/taichuy/1flowbase/main/scripts/powershell/docker-deploy.ps1 | iex

PowerShell 同样会询问是否恢复备份；或先下载脚本后使用 -RestoreBackup C:\safe\system.1fb-backup。

Windows CMD:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/taichuy/1flowbase/main/scripts/powershell/docker-deploy.ps1 | iex"

---

Run From Source

This path is for developing 1flowbase itself.

Requirements: Node.js >= 24.0.0, pnpm, the latest stable Rust, and Docker for local middleware.

git clone https://github.com/taichuy/1flowbase.git
cd 1flowbase

docker compose -f docker/docker-compose.middleware.yaml up -d

cd web
pnpm install
pnpm dev

Frontend:

http://127.0.0.1:3100

To develop Native React blocks with the optional External npm Pack, start the companion repository in another terminal. Vite proxies the same production path, /external-npm/, to port 4174 by default:

git clone https://github.com/taichuy/1flowbase-web-external-npm.git
cd 1flowbase-web-external-npm
pnpm install --ignore-scripts
pnpm dev

Override VITE_EXTERNAL_NPM_PROXY_TARGET in web/app/.env when the pack server uses another address.

Start backend services:

cd api
# Copy api/apps/api-server/.env.example to .env before the first run.
cargo run -p api-server --bin api-server
cargo run -p plugin-runner --bin plugin-runner

Default backend endpoints:

API Server: http://127.0.0.1:7800
Plugin Runner: http://127.0.0.1:7801

Script-assisted startup:

node scripts/node/dev-up.js
node scripts/node/dev-up.js status
node scripts/node/dev-up.js stop
node scripts/node/dev-up.js restart

See scripts/README.md for more configuration options.

---

Common Use Cases

Have an agent build and continuously manage an internal application

Local or external Agent
  -> MCP Gateway
  -> create Data Models and relations
  -> publish CRUD and Workflow Extension APIs
  -> assemble Native React blocks
  -> inspect and continuously evolve the running application

This is the primary full-stack path formed by the four foundations: the agent operates the control plane through MCP, the Application Backend handles data and APIs, and Native React blocks provide the human interface. The AI Gateway is connected on demand only when the application also needs to serve governed model endpoints externally.

Deliver an application backend without assembling a separate backend stack

Data Model
  -> PostgreSQL table / columns / indexes / relations
  -> generated CRUD runtime and OpenAPI
  -> custom business logic via Workflow Extension APIs

Ideal for internal tools, management systems, operations dashboards, agent memory storage, content systems, and small-to-medium product backends.

Add custom human interfaces to agent-managed data

Data Model / custom APIs
  -> Native React blocks
  -> search, filters, forms, actions, and responsive layouts

The task planning board is a real example: the native React interface reads and updates records directly through the Data Model API, without a separate frontend-backend stack.

Publish a programmable upstream model for AI clients

External AI clients
  -> optional AI Gateway
  -> protocol translation
  -> model and tool workflows
  -> logs, traces, token usage, and final responses

The client calls a single model name, and 1flowbase can run cross-provider workflows behind it. Suitable for multimodal enhancement, Fusion-style review, model cascading, structured output validation, and programmable coding model flows.

---

Transparency and Security

1flowbase is committed to providing a transparent, self-hosted environment for AI workflow execution.

Recommended principles:

• self-hosted first
• transparent model chains
• auditable node calls
• traceable token usage
• configurable log retention
• explicit model and workflow configuration

1flowbase does not advocate silently replacing models without the user's knowledge. Every published endpoint should be clearly configured, observed, and governed by the project owner.

---

Guides

• Make GLM-5.2 See Images in Claude Code with 1flowbase
• Fusion-Style Workflows: Publish a Multi-Model Panel as an Observable Virtual Model
• 1flowbase Wiki

---

Repo Layout

web/          Frontend root, powered by pnpm + Turbo
api/          Rust backend workspace
api/apps/     Backend service entry points
api/crates/   Shared backend crates
api/plugins/  Plugin workspace, HostExtension manifests, and templates
docker/       Local middleware orchestration and self-hosted stack
scripts/      Development, testing, verification, and debugging scripts

---

Contributing

Community contributions are very welcome. Before submitting a pull request, run the following verification script:

node scripts/node/verify.js repo

Project development guidelines:

• AGENTS.md
• web/AGENTS.md
• api/AGENTS.md

---

Friend Links

• Linux.do - Learn AI, on L Station.
• Aionui - Remotely control AI to work via mobile phone.
• OfficeCLI - Office suite designed for AI agents.
• deepseek-pp - DeepSeek web chat browser extension.
• MuseAI - Local AI companion, text adventure, and story immersion app.
• FrontAgent - AI Agent system designed specifically for front-end engineering.
• RedBox - Localized AI creative workbench for Xiaohongshu creators.

---

License

This project is licensed under the Apache-2.0 open-source license.

---

Contributors

---

Star History

---