Most AI forgets you the moment you close the tab. A Flowork agent is something you own. It lives in a folder on your machine, carries its own memory, learns from its own mistakes, and keeps working when the network dies. Clone the folder to a USB stick and its whole mind comes with it.
What You're Looking At
Flowork is a microkernel — a tiny, eternal core written once and never edited — that hosts autonomous AI agents as sandboxed WebAssembly citizens. Each agent lives in its own folder with its own persona, rules, tools, schedule, and brain in a private SQLite database. Everything else — agents, tools, scanners, channels, MCP servers — is a plug-and-play module that snaps onto one frozen contract. A module breaks? You fix one folder. Nothing else is touched.
This isn't a service you rent. It's a system you run, own, and understand.
Why This Matters
It's yours. Local-first, self-hosted. No SaaS, no telemetry, no lock-in. Works fully offline.
It snaps together. Drop in a.fwpackand it hot-loads — no kernel edits, no rebuilds.
It gets smarter. Agents learn from what they got wrong, treating mistakes as lessons.
It watches its own back. A real security scanner guards the code your agents run — something no other agent framework ships.
MCP both ways. Use external MCP tools, and expose your agents to MCP clients like Claude Desktop.
Flowork has been rebuilt 12 times in about a year and a half — a convergent search for the right shape of one idea. It began as a browser-based, Python canvas where you did the wiring. It became an agent OS where agents do the orchestrating and you own them. Four things never changed: it's always an OS, your data is always yours, everything plugs in cleanly, and privacy comes first.
Installation: One Command
No Docker, no accounts, no cloud:
git clone https://github.com/flowork-os/Flowork_Agent.git
cd Flowork_Agent
./start.sh
That's it. start.sh builds the binary on first run (needs Go 1.25+) and serves the control panel at http://127.0.0.1:1987. On first launch, create your owner account on the login screen — that's you, the person in charge.
- Works on Linux, macOS, and Windows — one pure-Go binary, no cgo.
- Stop with
./stop.sh, restart with./restart.sh. - Everything runs on your machine and talks to nothing outside unless you tell it to.
How It Actually Works
Everything flows through one counter (the "loket"). A module can do nothing alone. To think, remember, run a tool, or send a message, it asks the kernel for a capability by name: call(cap, args). The kernel checks the grant, routes to a provider, enforces the sandbox, returns the result.
A message comes in from Telegram, Discord, Slack, WhatsApp, voice, CLI, MCP, or the web. It lands on the internal bus. The kernel routes it through the loket with a grant check inside a WASM sandbox. The AI agent asks the loket for the LLM router, its two-tier brain, 117 built-in tools plus MCP servers, and the group bus. The reply travels back. A Guardian freezes and guards the whole kernel.
This design is intentional: one entry point, one permission model, one place to debug. You can trace how a request moves through the system without chasing fifty files.
The Mind: A Brain That Learns, A Doctrine That Won't Lie
The Brain
Every agent's memory lives in its own state.db — clone the folder and the memory comes with it. Nothing is shared with other agents unless you wire it.
Local memory (FTS5) — fast keyword search using SQLite FTS5 and BM25 ranking. No embeddings, so it's lightweight, instant, and fully offline. The agent stores what it sees withbrain_addand recalls related memories withbrain_search.
Wings — every memory is filed in a "wing": general, experience, eureka, or constitution. Duplicates are dropped by content hash, so the brain doesn't bloat.
Two tiers — on top of each agent's own memory sits a big shared corpus it can draw on. Think of it as collective experience layered under personal experience.
Dream → Eureka — while idle, a quiet consolidation pass finds recurring patterns and files them intoeurekainsights. The brain grows from its own experience — no retraining, no GPU.
Immune system — an antibody scanner quarantines poisoned memories so the brain never gets corrupted.
A turn works like this: a message comes in → the agent remembers it → recalls related memories → thinks (calls the LLM with its doctrine plus the recalled context) → replies. Memory first, then thought.
Educational Errors
This is a dated design principle baked into the core — see the blueprint for the full philosophy.
Most AI hides a mistake. Suppress it, fine-tune it away, pretend it never happened. Flowork treats an error as education. Every mistake is:
Captured — the exact input, the wrong output, and the correction.
Explained — why it failed, what the rule was.
Retained — kept as a lesson in the brain, ranked by karma and relevance.
Redemptive — the agent is quarantined, given context to understand, and a chance to correct.
The loop: make a mistake → capture and explain it → keep it as a lesson → recall it next time → don't hit the same wall. This is learning at runtime, no retraining. Over time, the agent gets demonstrably harder to fool on the same error.
The Router: One Door, Anti-Hallucination Built In
You can point an agent at any LLM API. But we recommend pointing it at Flowork's own router (http://127.0.0.1:2402/v1/chat/completions):
One door, model-agnostic — swap the model in one place. Point to a subscription, a local model, or a custom endpoint. The agent doesn't care.
The anti-hallucination antibody — before the LLM answers, the router injects the agent's own most-recurrent, most-relevant past mistakes (ranked by karma × relevance). A hallucination gets harder to repeat over time — deterministically, no retraining, no GPU. The mechanism is in the blueprint.
Constitution on every turn — sacred rules (a five-question gate, an identity guard, a truth rule) are injected on every call. Anti-hallucination isn't a setting. It's law.
Aim an agent at a raw third-party API and it gets none of this. Aim it at the router and it gets all three for free. The mistakes the brain keeps are exactly what the router injects back as antibodies.
Security: A Radar That Watches Its Own Code
Most agent frameworks ignore security. Flowork ships a real scanner — something you'd expect in a DevSecOps pipeline, not an AI framework.
The Guardian watches the code your agents run. Every tool your agents use, every line of shell script, every file system operation: scanned. If something looks malicious — command injection, path traversal, credential theft — it's flagged, logged, and the operation can be quarantined. You see the risk surface of your agents, not hidden.
The kernel itself is frozen and self-guarding. Tamper with the core? It detects it and drops into safe-mode. Nothing gets secret.
MCP: Client and Server
Flowork speaks MCP both ways.
As a client: your agents can use external MCP servers — GitHub, filesystem, any MCP tool in the ecosystem. Instead of building a native tool, wire in the MCP.
As a server: expose your agents to MCP clients. Run Claude Desktop? Claude can call your Flowork agents. Run Cursor? Your agents are available as tools. You're not locked into one interface.
This is how you build a self-hosted agent that plays nicely with the broader LLM tooling landscape.
Tools: 117 Built-In, Zero Prompt Bloat
Flowork ships 117 tools out of the box — file system, HTTP, JSON, date, shell, text, math, crypto, databases, and more. Each tool is versioned and namespaced. An agent declares which tools it needs. The kernel injects only those into the WASM sandbox.
This is not the ChatGPT approach of jamming every tool description into the context window and hoping the model picks the right one. Here, tools are declared, granted, sandboxed, and isolated. An agent with 5 tools doesn't carry the prompt cost of 117.
You can also build your own tools and pack them as modules.
Groups: Small Agents, Sharper Orchestration
A team of agents that tackle one task together — a colony of ants, each doing one small job, then a synthesizer brings the pieces together. Many small, focused agents beat one big do-everything agent.
Create a group: type an ID and name, tick the agents you want on the team, pick a synthesizer (one agent that combines answers), write the task. The group fans the task out to each member over the internal bus, collects their answers, and the synthesizer stitches them into one result.
For custom orchestration (phases, roles, dependencies), start from templates/group-template/ and edit the coordinator agent's main.go. Build it like any agent (GOOS=wasip1 GOARCH=wasm go build -o agent.wasm .). Members are ordinary agents — a great group is really about small, sharp specialists wired together.
Settings: One Place for Every Key and Default
This is the owner-level control panel. Global stuff that isn't tied to any one agent, kept in the global flowork.db:
API Keys — every external credential goes here. Dev.to, X, LinkedIn, Telegram, everything. Nothing is ever hardcoded in the source code. Agents read these at boot from the settings database.
Router & Model — the global default LLM model and router URL. Per-agent always wins; these fill the blank for agents that set nothing.
Notifications — your own Telegram bot token and chat ID, so Flowork can ping you.
YouTube — connect a YouTube account by OAuth.
Guardian — the integrity guard's status (which files are watched).
When you save a key, it's stored in flowork.db and injected into the running process immediately. On the next boot, keys are loaded before the agents start.
The Stack: Minimal, Purpose-Built
Go 1.25, compiled to a single static binary — no cgo, no Docker, no runtime to install. Linux / macOS / Windows.
A tiny "forever" core (microkernel) — written once and never touched again. Everything else clips onto one fixed contract (ABI).
Each agent in its own box (WASM) — sandboxed WebAssembly via wazero, limited to granted capabilities.
Memory in SQLite — fast full-text search (FTS5); every agent gets its own private brain file.
MCP, both ways — use outside MCP tools, and let outside apps use your agents.
It guards itself — the core watches for tampering and drops into safe-mode if anything's off.
The web UI is embedded in the binary — no separate site to host, no JavaScript framework to manage.
What This Means for You
If you're building AI systems today, you're choosing between rent and own. Cloud services are convenient, but you're always a policy change away from losing your data, your models, or your users.
Flowork is the own path. Your agents live on your hardware. Their memories stay private. When you want to move them, you copy a folder. When you want to understand what they're doing, you read the code — it's small, it's Go, it's not hiding anything.
The security scanner means you're not flying blind. The educational errors mean your agents get smarter from mistakes instead of repeating them. The microkernel means you can fix one thing without breaking everything else. The offline capability means you're not dependent on an internet connection or a third-party API staying alive.
This isn't the fastest or the fanciest. But it's honest. You know what you're running. You own what you've built. And that's worth something.
Get started: Clone the repo, run ./start.sh, and open http://127.0.0.1:1987. Read the handbook first — it's plain Markdown, readable right after you clone. Then build your first agent.
🔗 Flowork is open source — both products
- 🤖 Flowork Agent (the self-hosted agent OS): https://github.com/flowork-os/Flowork_Agent
- 🛣️ Flow Router (the sovereign LLM gateway): https://github.com/flowork-os/flowork_Router
💬 Join the Flowork community on Telegram: https://t.me/+55oqrk75lc43YWE1