English | 简体中文
Community: WeChat | WeChat Official Account | Twitter
Build full-stack agent-native applications on four open-source foundations: an AI Gateway, an MCP Gateway, a built-in Application Backend, and Native React frontend blocks.
1flowbase gives local agents, model clients, external systems, and people independent ways to use the same self-hosted application platform. A local agent can connect only to the MCP Gateway to build and operate applications with its existing model setup. Connecting that client to the AI Gateway is optional and adds compatible model endpoints, multi-model workflows, and detailed execution traces.
Local agents -> 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
Use any foundation independently, or combine them around one 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 | Turn 1flowbase capabilities into progressively discoverable tools; organize tools, mappings, groups, bindings, policies, upstream MCP connections, and reusable bundles |
| Application Backend | Define Data Models that materialize PostgreSQL tables, fields, indexes, and relations; generate governed CRUD APIs and publish custom workflow-powered endpoints |
| 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 use MCP to create Customer and Ticket Data Models, assemble a workflow-backed /api/ex/tickets/escalate operation, and build the React interface. External systems call the generated backend APIs, while people work in the interface. If the same local agent also points its model endpoint at the AI Gateway, it gains published virtual models with routing, model composition, and full logs; the application does not depend on that optional connection.
The MCP Gateway projects platform capabilities into an agent-oriented virtual UI. An agent can progressively discover the relevant domain, inspect a tool contract, call it, verify the resulting state, and continue building without requiring a new hard-coded frontend flow for every 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
Define a Data Model in 1flowbase and publish it. The platform materializes the PostgreSQL schema and exposes model-aware List, Get, Create, Update, and Delete APIs with generated OpenAPI contracts. Use Workflow Extensions when CRUD is not enough and publish custom business operations under /api/ex/{slug}.
Data Model definition
-> PostgreSQL table / columns / indexes / relations
-> generated CRUD runtime APIs + OpenAPI
Workflow
-> custom input and output contract
-> published /api/ex/{slug} operation
Write frontend blocks with standard React/TSX, Hooks, events, and CSS. 1flowbase compiles and mounts each block in an isolated Shadow DOM runtime, while controlled catalogs and context contracts expose the platform capabilities the block is allowed to use.
export default function StatusCard({ ctx }) {
const status = ctx.inputs.status;
return <button onClick={() => ctx.outputs.publish({ action: 'retry' })}>
{status}
</button>;
}Keep GLM-5.2, DeepSeek, or another strong text coding model as the main planner, then 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
1flowbase includes a fusion template. Your client calls one model name; 1flowbase asks several branch models, runs a synthesis model, returns the final answer, and keeps every branch visible.
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
Build the workflow once, then expose it through common model APIs:
| 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 |
Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/taichuy/1flowbase/main/scripts/shell/docker-deploy.sh | shWindows PowerShell:
irm https://raw.githubusercontent.com/taichuy/1flowbase/main/scripts/powershell/docker-deploy.ps1 | iexWindows CMD:
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/taichuy/1flowbase/main/scripts/powershell/docker-deploy.ps1 | iex"Use this path when you want to develop 1flowbase itself.
Requirements: Node.js >= 24.0.0, pnpm, 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 devFrontend:
http://127.0.0.1:3100
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-runnerDefault 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 restartSee scripts/README.md for more options.
1flowbase is not just a model proxy, a bag of MCP servers, or another chat UI.
| Tool category | What it usually does | How 1flowbase is different |
|---|---|---|
| LLM gateway / model router | routes one request to one provider or model | composes multiple model and tool nodes into one workflow-backed virtual model |
| MCP server / gateway | exposes or aggregates tools for agents | exposes the 1flowbase application control plane while also connecting and governing upstream MCP tools |
| Backend-as-a-Service / backend builder | provides tables and generic CRUD endpoints | materializes governed PostgreSQL Data Models and combines generated CRUD with workflow-powered custom APIs |
| AI workflow builder | builds an AI app or workflow | exposes the workflow through model APIs and makes the surrounding application operable through MCP |
| Agent application framework | helps developers code agent graphs and interfaces | combines a visual runtime, agent-facing control plane, protocol publishing, and Native React application surfaces |
| Observability / cost tracker | shows token or spend totals | connects cost to workflow nodes, model calls, tool callbacks, and trace logs |
Model serving plane: AI Gateway (optional for external clients)
Agent control plane: MCP Gateway
Data and API plane: Application Backend
Human experience plane: Native React frontend blocks
1flowbase provides all four foundations in one self-hosted platform.
Call a published workflow from compatible clients that support custom model endpoints.
Trace model requests, node inputs and outputs, tool callbacks, response content, latency, and errors.
Screenshot / UI mockup / chart
-> vision tool
-> structured visual context
-> strong coding model
-> patch, plan, or explanation
Useful for UI reconstruction, frontend debugging, visual regression analysis, chart reading, PDF page understanding, and design-to-code workflows.
Architecture proposal
-> cheap broad reviewer
-> strong reasoning reviewer
-> provider-diverse reviewer
-> synthesis model
-> final recommendation
Useful for architecture review, research synthesis, code review, document review, and high-stakes agent decisions.
Simple classification -> small model
Formatting -> small model
Complex reasoning -> strong model
Final verification -> verifier node
Use verifiers, JSON Schema validation, and formatter nodes before returning the final result. This is useful for JSON outputs, API responses, tool call parameters, code patches, document generation, and automated task results.
Code generation -> test / lint check -> reviewer node -> fix node -> final patch
The client calls one model name while 1flowbase runs your workflow behind it.
- visual workflow editor
- multi-node workflow orchestration
- virtual model endpoint publishing
- OpenAI Responses protocol support
- OpenAI Chat Completions protocol support
- Claude-compatible Messages protocol support
- streaming response support
- mounted LLM tools for multimodal and branch-model workflows
-
fusionworkflow template - execution logs
- tool callback traces inside 1flowbase workflows
- application-level token consumption statistics
- prompt and model configuration version history
- MCP Gateway with progressive
mcp.list,mcp.get, andmcp.calldiscovery - MCP tool, mapping, group, binding, discovery policy, and upstream connection management
- reusable MCP bundle import, export, validation, and local library flows
- dynamic Data Models that materialize PostgreSQL tables, fields, indexes, and relations
- generated Data Model CRUD runtime APIs and OpenAPI contracts
- custom Workflow Extension APIs published under
/api/ex/{slug} - Native React/TSX frontend blocks with Hooks, CSS, events, and Shadow DOM isolation
- controlled frontend component catalog, code studio, responsive context, and data binding
- deeper local agent conversation collection
- session search and playback
- Token Bill of Materials by prompt, history, tool definitions, command outputs, media inputs, and nodes
- abnormal cost detection and optimization suggestions
- session export and Recall Pack generation
- more Claude Code / Codex / OpenCode / Cline / Continue templates
- broader agent-ready MCP Virtual UI coverage across product domains
- more end-to-end application recipes combining MCP management, Application Backend, frontend blocks, and optional AI Gateway serving
- broader low-code authoring on top of the four application foundations
- team workspace and multi-tenant management
- permissions, approval, audit, and cost governance
- support for more local AI agent clients
- template market and workflow recipe ecosystem
The four foundations are implemented and usable today. They are composable rather than mandatory stages: an external agent can use the MCP Gateway without routing its model traffic through the AI Gateway. Broader low-code authoring, team governance, and the template ecosystem are still evolving.
1flowbase is designed for transparent, self-hosted AI workflow execution.
Recommended principles:
- self-hosted first
- transparent model chains
- auditable node calls
- traceable token usage
- configurable log retention
- sensitive data masking
- explicit model and workflow configuration
1flowbase does not advocate stealthy model replacement. Published endpoints should be configured intentionally, observed clearly, and governed by the project owner.
- 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
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
Contributions are welcome. Before submitting a pull request, run:
node scripts/node/verify.js repoProject guidelines:
- 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.
Codex was used to:
- redesign MCP configuration workflows
- implement and review Rust backend changes
- improve React components
- debug integration issues
GPT-5.6 was used for:
- designing agent workflows
- validating MCP capability patterns
- improving architecture decisions
This project is licensed under Apache-2.0.
If you want agents to build and operate self-hosted applications across AI, MCP, backend, and React surfaces, give 1flowbase a star.