DEV Community

floworkos
floworkos

Posted on

How to Install and Build Apps in Flowork

#go #webassembly #agents #microservices

Installing Flowork from Source & Building Your First App

Flowork is a microkernel agent OS — a tiny, unchanging core that hosts autonomous AI agents as sandboxed WebAssembly citizens. Unlike most AI tools that forget you the moment you close the browser, a Flowork agent is something you own: it lives on your machine, carries its own memory, and keeps working offline.

Prerequisites

You'll need Go 1.25+ installed on your machine. Flowork compiles to a single static binary with no Docker, cgo, or external runtime dependencies. It runs on Linux, macOS, and Windows.

Installing Flowork

The installation process is straightforward:

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

The start.sh script builds the binary on first run and serves the control panel at http://127.0.0.1:1987. On first launch, you'll create your owner account on the login screen — you are the administrator of your Flowork instance.

To stop and restart:

  • ./stop.sh — shuts down the daemon
  • ./restart.sh — rebuilds and restarts

Everything runs on your machine and talks to nothing outside unless you explicitly configure it.

Understanding the Architecture

Flowork's design centers on one frozen contract — the "loket" (one door). The microkernel never changes. Everything else — agents, tools, scanners, channels, MCP servers, and apps — snaps on as a plug-and-play module. If a module breaks, you fix that one folder; nothing else is touched.

The core is written in Go and embedded with the web UI. Each agent runs as its own WebAssembly sandbox (via wazero) with its own database for memory (SQLite with full-text search) and a private workspace. Memory stays local; capabilities are granted explicitly through the loket.

Installing Apps & Agents

Apps — Self-contained Programs

Apps are little programs with dual purpose: both a screen you click and a set of tools your agents can use. Flowork ships with example apps like a quant desk and a notepad.

To install an app:

  1. Navigate to the App menu and locate the Installed tab
  2. Click the upload zone or button to add a .fwpack file
  3. Flowork validates the package and requests your consent (since apps can run real programs on your computer)
  4. Once installed, you can Open it in a sandboxed frame (it can only communicate with Flowork through declared operations in its manifest)
  5. To remove an app, click Uninstall on its card

Agents — Autonomous Citizens

Agents are autonomous entities with their own folder, memory (brain), personality, rules, and capability list. They share nothing unless you wire them. Each agent is its own WebAssembly sandbox.

To install an agent:

  1. Go to the AI Agent menu
  2. Drag a .fwagent.zip file into the drop zone (must contain manifest.json + agent.wasm, max 64 MiB)
  3. The kernel hot-loads it into ~/.flowork/agents/<id>.fwagent/ — no restart required
  4. Configure it via the Setting popup: assign an LLM router, set its system prompt, grant tools (Telegram, fetch, filesystem, KV store), and add a schedule if needed
  5. Flip the switch to Active to enable it

Creating Your Own App (manifest.json + Sandbox UI)

Apps follow a simple structure. Each app has one state and two drivers — the same logic runs whether a human clicks a button or an agent calls a tool.

Create a folder under apps/my-app/ with three files:

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

manifest.json example:

{
  "id": "my-app",
  "kind": "app",
  "ops": [
    { "name": "calculate", "args": { "x": "number", "y": "number" } },
    { "name": "fetch_data", "args": { "url": "string" } }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Every operation you declare becomes both a GUI button and an agent tool simultaneously. The ui/index.html is sandboxed in an iframe and can only call Flowork through validated ops — it sends {op, args}, the host checks the op is declared in the manifest, runs it, and returns the result.

core.py handles the headless logic. It reads line-JSON from stdin (the operation request) and writes line-JSON to stdout (the result). Both the UI button and an agent tool invoke the same function.

Creating Your Own Agent (WebAssembly + Manifest)

Agents are WebAssembly modules that interact with Flowork through the loket (capability broker). The easiest path is to use the agent template:

my-agent.fwagent/
├─ manifest.json   (the contract)
├─ agent.wasm      (compiled WebAssembly)
├─ main.go         (your logic)
├─ prompt.md       (system persona)
└─ doktrin.md      (lessons / doctrine)
Enter fullscreen mode Exit fullscreen mode

manifest.json declares your capabilities and exposed functions:

{
  "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

capabilities_required is your permission list — an agent can only do what's declared. exposes_rpc lists the functions it offers to Flowork.

Write your logic in Go and compile to WebAssembly:

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

Zip the entire my-agent.fwagent/ folder (including the compiled .wasm file) as my-agent.fwagent.zip, then drag it into the AI Agent install zone.

Using .fwpack for Distribution

Apps and agents can be packaged as .fwpack files (which are zip archives with specific structure) for easy distribution and installation. The manifest declares the module type (kind: "app", kind: "agent", kind: "channel", or kind: "scanner") and all required metadata.

A Principle: One State, Two Drivers

The core design principle is that your code is written once. Whether a human clicks a button in the UI or an agent invokes a tool, the same logic runs on the same state. This eliminates duplication and keeps behavior consistent across human and machine interfaces.

Next Steps

Once Flowork is running:

  1. Explore the built-in examples (notepad, quant desk)
  2. Experiment with installing a simple agent
  3. Try creating a minimal app with one operation
  4. Set up MCP connections to extend agent capabilities
  5. Read about Threat Radar to enable the security scanner for your agents
  6. Configure Connections to let agents reach external tools and channels

Flowork is designed to be extended piece by piece without touching the core. Each module you add or remove is isolated; the system remains stable because the kernel never changes.

Flowork is open source — both products:

Top comments (0)