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

如何在 Flowork 中安装和构建自定义应用、智能体及扫描器

Getting Flowork running is a single command — no Docker, no accounts, no cloud dependencies. 只需一条命令即可运行 Flowork——无需 Docker、无需账户、无需云端依赖。

git clone https://github.com/flowork-os/Flowork_Agent.git cd Flowork_Agent ./start.sh

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. start.sh 会在首次运行时构建二进制文件（需要 Go 1.25+），并在 http://127.0.0.1:1987 提供控制面板。首次启动时，请在登录界面创建您的所有者账户。该系统支持 Linux、macOS 和 Windows。使用 ./stop.sh 停止，使用 ./restart.sh 重启。所有内容均在本地运行，仅在您明确配置时才会与外部通信。

Understanding Flowork’s Architecture

理解 Flowork 的架构

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. Flowork 基于微内核构建——一个微小、永久的核心，编写一次后便不再修改。其他所有组件都通过单一的固定契约进行挂载：智能体、工具、扫描器、通道、MCP 服务器和应用。这意味着您可以破坏某个组件，只需修复该文件夹，而不会影响其他任何部分。

The stack: 技术栈：

Go 1.25, compiled to a static binary with no cgo, no Docker, no external runtime Go 1.25，编译为静态二进制文件，无 cgo、无 Docker、无外部运行时
WASM agents running sandboxed via wazero, with only granted capabilities 通过 wazero 在沙箱中运行的 WASM 智能体，仅拥有被授予的权限
SQLite for fast full-text search and each agent’s private memory 用于快速全文搜索及每个智能体私有内存的 SQLite
MCP (Model Context Protocol) bidirectionally — use external tools and expose your agents to outside clients 双向 MCP（模型上下文协议）——使用外部工具并将您的智能体暴露给外部客户端
Embedded web UI in the binary itself — no separate server to host 二进制文件中内置的 Web UI——无需单独的服务器进行托管
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. 所有操作都通过一个中央“loket”（柜台）进行。当模块需要思考、记忆、运行工具或发送消息时，它会按名称向内核请求权限：call(cap, args)。内核会检查授权、路由至提供程序、强制执行沙箱并返回结果。

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. 应用是自包含的程序——每一个既是一个可点击的屏幕，也是一组智能体可以使用的工具。Flowork 附带了两个示例：量化工作台和记事本。

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. 将 .fwpack 文件拖入“应用”菜单的“已安装”选项卡中。由于应用可以在您的计算机上运行真实程序，因此安装需要您先同意。安装后，您可以打开它，在受限的沙箱框架中启动应用。应用只能通过经过验证的操作与 Flowork 通信：它请求 {op, args}，宿主检查该操作是否在应用的清单中声明，运行它并返回结果。您可以卸载它以将其移除。

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)

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. 您声明的每一个操作都会同时成为 GUI 按钮和智能体工具。逻辑只需编写一次；人类点击和智能体调用都会以相同的状态和两个不同的驱动程序执行它。

Building and Installing WASM Agents

构建和安装 WASM 智能体

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. 智能体是居住在您机器上的自主 AI 公民。每个智能体都有自己的文件夹、内存、个性、规则和允许的权限列表。除非您将它们连接在一起，否则它们之间不共享任何内容。

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. 导航至“AI 智能体”菜单，将 .fwagent.zip 拖入放置区。该文件必须包含 manifest.json 和 agent.wasm（最大 64 MiB）。它会被解压到 ~/.flowork/agents/<id>.fwagent/，内核会热加载它——无需重启。使用 ↻ 刷新按钮进行重载。

Building a custom agent 构建自定义智能体

The easiest starting point is a template. An agent folder zipped as .fwagent.zip contains: 最简单的起点是使用模板。压缩为 .fwagent.zip 的智能体文件夹包含：

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)

Here’s the essential manifest.json structure: 以下是基本的 manifest.json 结构：

{
  "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": {} }
    }
  ]
}

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 . Then zip the folder and drag the .fwagent.zip into the AI Agent menu. capabilities_required 数组是权限列表——智能体只能执行明确声明的操作。exposes_rpc 数组定义了它向系统提供的函数。使用 Go 的 WASM 工具链构建：GOOS=wasip1 GOARCH=wasm go build -o agent.wasm . 然后压缩文件夹并将 .fwagent.zip 拖入“AI 智能体”菜单。

Once installed, use the ⚙️ Setting button on the agent card to configure: 安装完成后，使用智能体卡片上的 ⚙️ 设置按钮进行配置：

Router — which LLM endpoint and model it uses 路由——它使用的 LLM 端点和模型
Prompt — its system prompt (persona and rules) 提示词——其系统提示词（个性与规则）
Tools — which capabilities it’s granted 工具——它被授予的权限
Schedule — recurring jobs in cron format 计划——Cron 格式的定期任务
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. Flowork 附带内置的“威胁雷达”（Threat Radar）——一个实时安全仪表板，监控智能体运行的代码，并允许您扫描自己的代码或授权的外部目标。没有其他智能体框架包含此功能。

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). 威胁雷达显示一个雷达扫描界面，包含三个数字：运行次数（总执行数）、发现（检测到的问题）和严重程度（如果有严重问题则显示为红色，如果安全则显示为绿色）。

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) 扫描目标——打开扫描表单以选择工具、目标、可选参数和类别（immune = 加固您自己的代码，pentest = 授权的外部目标）
≣ 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. 工具和目标列表来自所有者可编辑的白名单。Flowork 不会运行未经批准的工具或触碰未经批准的目标，且中间没有 shell。

Building custom scanner checks 构建自定义扫描检查

A check is a nuclei template — a small YAML that specifies what to look for. 检查是一个 nuclei 模板——一个指定查找内容的小型 YAML 文件。