DEV Community

floworkos
floworkos

Posted on

How to Install and Build Custom Apps, Agents, and Scanners in Flowork

#flowork #go #agents #microkernel

Getting Flowork running is a single command — no Docker, no accounts, no cloud dependencies.

git clone https://github.com/flowork-os/Flowork_Agent.git
cd Flowork_Agent
./start.sh
Enter fullscreen mode Exit fullscreen mode

start.sh builds the binary on first run (requires 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. The system works on Linux, macOS, and Windows. Stop with ./stop.sh, restart with ./restart.sh. Everything runs locally and communicates outside only when you explicitly configure it.

Understanding Flowork's Architecture

Flowork is built as a microkernel — a tiny, permanent core written once and never edited. Everything else snaps onto a single frozen contract: agents, tools, scanners, channels, MCP servers, and apps. This means you can break one component, fix that folder alone, and nothing else is affected.

The stack:

  • Go 1.25, compiled to a static binary with no cgo, no Docker, no external runtime
  • WASM agents running sandboxed via wazero, with only granted capabilities
  • SQLite for fast full-text search and each agent's private memory
  • MCP (Model Context Protocol) bidirectionally — use external tools and expose your agents to outside clients
  • Embedded web UI in the binary itself — no separate server to host
  • Built-in security scanner watching the code your agents execute

Everything flows through one central "loket" (counter). When a module needs 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, and returns the result.

Installing and Building Apps

Apps are self-contained programs — each is both a clickable screen and a set of tools agents can use. Two examples ship with Flowork: a quant desk and a notepad.

Installing an app

Drop a .fwpack file into the Installed tab of the Apps menu. Because an app can run real programs on your computer, installation requires your consent first. After installing, you Open it to launch the app in a locked-down sandboxed frame. The app can only communicate with Flowork through validated ops: it asks {op, args}, the host checks the operation is declared in the app's manifest, runs it, and returns the result. You can Uninstall to remove it.

Building a custom app

Create a folder with three things:

apps/my-app/
├─ manifest.json   kind:"app" + the list of operations
├─ core.py         the headless logic (talks over stdin/stdout, line-JSON)
└─ ui/index.html   the screen (sandboxed iframe)
Enter fullscreen mode Exit fullscreen mode

Every operation you declare becomes both a GUI button and an agent tool simultaneously. Write the logic once; a human clicking and an agent calling both execute it with the same state and two different drivers.

Building and Installing WASM Agents

Agents are autonomous AI citizens living on your machine. Each has its own folder, memory, personality, rules, and list of permitted capabilities. They share nothing unless you wire them together.

Installing an agent

Navigate to the AI Agent menu and drag a .fwagent.zip into the drop zone. The file must contain manifest.json and agent.wasm (max 64 MiB). It extracts to ~/.flowork/agents/<id>.fwagent/ and the kernel hot-loads it — no restart required. Use the ↻ Refresh button to reload.

Building a custom agent

The easiest starting point is a template. An agent folder zipped as .fwagent.zip contains:

my-agent.fwagent/
├─ manifest.json   the contract (id, version, kind, capabilities, exposed RPC methods)
├─ agent.wasm      the compiled agent
├─ main.go         your logic
├─ prompt.md       its system persona and rules
└─ doktrin.md      its "lessons doctrine" — mistakes turned into learning
Enter fullscreen mode Exit fullscreen mode

Here's the essential manifest.json structure:

{
  "id": "my-agent",
  "version": "1.0.0",
  "kind": "agent",
  "display_name": "My Agent",
  "entry": "agent.wasm",
  "abi_version": 1,
  "memory_max_mb": 16,
  "timeout_call_ms": 120000,
  "capabilities_required": [
    "net:fetch:http://127.0.0.1:1987/api/kernel/call",
    "state:read",
    "state:write",
    "time:read"
  ],
  "exposes_rpc": [
    {
      "name": "handle_message",
      "description": "Handle one message.",
      "input_schema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

The capabilities_required array is the permission list — the agent can only do what's explicitly declared. The exposes_rpc array defines the functions it offers to the system.

Build with Go's WASM toolchain:

GOOS=wasip1 GOARCH=wasm go build -o agent.wasm .
Enter fullscreen mode Exit fullscreen mode

Then zip the folder and drag the .fwagent.zip into the AI Agent menu.

Once installed, use the ⚙️ Setting button on the agent card to configure:

  • Router — which LLM endpoint and model it uses
  • Prompt — its system prompt (persona and rules)
  • Tools — which capabilities it's granted (Telegram, LLM router, KV store, filesystem workspace, outbound fetch)
  • Schedule — recurring jobs in cron format
  • Skills — extra skills to install

Building and Installing Security Scanners

Flowork ships a built-in Threat Radar — a live security dashboard that watches code your agents run and lets you scan your own code or an authorized external target. No other agent framework includes this.

The Threat Radar shows a radar sweep with three numbers: runs (total executions), findings (issues detected), and critical (shown in red if anything critical is active, green if clean). The critical number reflects the worst result from the latest scan of each target — it returns to green when you fix something.

Scanning with Threat Radar

Open the Threat Radar menu. In the top-right:

  • ⟳ Refresh — reload the scan list
  • ⊕ Scan Target — open the scan form to pick a Tool, a Target, optional Args, and a Category (immune = hardening your own code, pentest = an authorized external target)
  • ≣ Arsenal — browse the catalog of defensive auditors, tools, and detection checks

The tool and target lists come from an owner-editable allowlist. Flowork will not run a tool or touch a target that isn't approved, and there's no shell in the middle.

Building custom scanner checks

A check is a nuclei template — a small YAML that specifies what to look for:

id: exposed-env-file
info:
  name: Exposed .env file
  author: you
  severity: high
http:
  - method: GET
    path:
      - "{{BaseURL}}/.env"
    matchers:
      - type: word
        words:
          - "DB_PASSWORD"
Enter fullscreen mode Exit fullscreen mode

Add a single check by POSTing to /api/scanner/checks/add with { name, yaml }. It validates through nuclei -validate and lands in <nuclei-templates>/flowork-private/ to appear in the Arsenal.

For multiple checks, bundle them into a kind:scanner .fwpack:

my-scanner.fwpack (zip)
├─ plugin.json   { "id": "my-scanner", "kind": "scanner", "scanner": { "name": "...", "description": "..." } }
└─ checks/
   ├─ check-1.yaml
   └─ check-2.yaml
Enter fullscreen mode Exit fullscreen mode

Install with /api/scanner/packs/install. Every check is validated; the rest integrate into the Arsenal. Everything is owner-only and local; every check is validated; templates run inert; and scans only touch tools and targets on your allowlist.

Connections: Channels and MCP

The Connections menu provides one roof for everything coming in and out: channels (how people reach your agents) and MCP servers (external tools your agents can use).

Installing channel connectors

Channels are the doors people use to reach your agents: Telegram, Discord, Slack, WhatsApp, CLI, and others. Drop a .fwpack (a kind:channel pack) into the Connections menu. It validates, extracts to its own folder, and hot-loads — no restart needed.

Each connector card shows Enable / Disable, Config (set its token and settings — fields come from the manifest, secrets are masked), and 🗑 Uninstall. Native connectors show only Config.

Installing and using MCP servers

Using external MCP tools (MCP client mode). Paste the same mcpServers JSON you'd use in any MCP-compatible app:

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_TOKEN": "..." }
  }
}
Enter fullscreen mode Exit fullscreen mode

Hit Install + enable. Flowork starts that server and its tools become available to all agents. Untick per-agent later in each agent's Tools settings. Each MCP card shows its tools, Enable/Disable, and Uninstall buttons.

Exposing your agents as an MCP server. Flowork can also be the MCP server, so an outside AI app or IDE can drive your agents. It speaks MCP over stdio and exposes chat (talk to an agent — same path as Telegram or the CLI), task_list, task_run, and task_result. Point your external client at the flowork-mcp command; the target agent comes from FLOWORK_MCP_AGENT.

Building a custom channel connector

A channel connector is a kind:channel .fwpack. Its manifest declares the config fields it needs (such as a bot token), and the Config panel renders them. Start from templates/connector-template/, fill in the relay logic (a simple pipe: message in → agent → reply out), build, and drop the .fwpack in. For MCP clients, you build nothing — just paste a server's config or point an external client at Flowork's MCP server.

Project Structure

Understanding the layout helps when building:

Flowork_Agent/
├─ main.go + *.go ..................... microkernel + HTTP handlers (the "forever" core)
├─ start.sh / stop.sh / restart.sh .... run, stop, rebuild scripts
├─ internal/
│   ├─ kernel/ , kernelhost/ ......... WASM microkernel + capability broker
│   ├─ loket/ ........................ the central "counter" every module uses (the ABI)
│   ├─ guardian/ , protector/ ........ self-protection (tamper → safe-mode)
│   ├─ floworkdb/ , agentdb/ ......... databases (global + each agent's private brain)
│   ├─ tools/ ........................ built-in tools
│   ├─ scanner/ , scanapi/ .......... security scanner
│   ├─ triggers/ , scheduler/ , taskflow/ ... automation
│   ├─ connections/ , mcpclient/ , mcphub/ ... channels + MCP
│   └─ groupsapi/ , slashcmd/ , settingsapi/ , routerclient/ ...
├─ web/ ............................. control panel UI (index.html, js/, tabs/)
├─ apps/ ............................ sandboxed apps (flowalpha, notepad)
├─ agents/ .......................... installed agents (.fwagent folders)
├─ templates/ ....................... starting points (agent, group, connector, lens)
├─ cmd/ ............................. extra entry points (CLI, TUI, MCP, chat)
└─ sdk/ , doc/ , scripts/ , seeds/ , voice-backend/ ...
Enter fullscreen mode Exit fullscreen mode

The golden rule: the core (top-level *.go + internal/kernel) is written once and never edited. Everything you add is its own folder that snaps on.

Next Steps

After running ./start.sh and creating your owner account, explore each menu in the control panel. Each is documented and ready to extend. Start with a template — whether for an agent, app, connector, or scanner — and build outward. Everything you need to own your AI infrastructure locally is there.

Flowork is open source — both products:

Top comments (0)