DEV Community

floworkos
floworkos

Posted on

Build Sandboxed AI Apps for Flowork: The Complete Developer Guide

#python #ai #sandbox #framework

Apps in Flowork are self-contained programs that live inside the framework — each serves as both a clickable screen and a set of tools your agents can invoke. This dual nature means you write the logic once; humans and AI agents both run it through the same state. The quant desk and notepad ship as examples.

Understanding the App Model

Every app exists in two driver modes at once:

  • GUI mode: a user clicks a button in the sandboxed iframe.
  • Agent mode: an agent calls the same operation as a tool.

Because they share one state, both interaction paths execute identical headless logic. This "one state, two drivers" principle eliminates duplication and keeps behavior consistent across interfaces.

Installing and Managing Apps

The Apps menu has two tabs: Installed and Store.

Installing an app:

  • Upload a .fwpack file.
  • Since apps can run real programs on your machine, the system asks for your consent before installation completes.

Opening an app:

  • Launches the app in a locked-down sandboxed frame via an iframe.
  • The sandboxed app cannot talk to Flowork directly. Instead, it makes validated requests: it sends {op, args}, the kernel checks that the operation is declared in the app's manifest, executes it, and returns the result.
  • This sandboxing model ensures untrusted or buggy code cannot escape or corrupt the host.

Uninstalling:

  • Removes the app cleanly.

Directory Structure and Core Files

To build an app, create a folder under apps/<id>/ with exactly three files:

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

manifest.json

Declares the app kind and lists every operation. Each operation name you declare becomes both a GUI button (displayed to humans) and an agent tool (callable by AI agents).

core.py

The headless logic layer. It communicates with the kernel over stdin/stdout using line-delimited JSON. When a human clicks a button or an agent invokes a tool, this module receives the request and runs the business logic.

ui/index.html

The user-facing screen, rendered inside a sandboxed iframe. It can call operations by sending structured requests to the kernel; the iframe cannot access the host DOM or make raw network calls.

The Operations Bridge

Every operation you declare in the manifest automatically becomes:

  1. A GUI button in the sandboxed iframe for human users.
  2. An agent tool that agents can invoke via the loket (the kernel's capability broker).

When either a human or agent triggers an operation:

  1. The request travels to the kernel with the operation name and arguments.
  2. The kernel verifies the operation is declared in the app's manifest.
  3. The kernel routes the request to core.py for execution.
  4. core.py processes it and returns a result.
  5. The result travels back to the caller (GUI or agent tool invocation).

Sandboxing and Security

Apps run in a WASM sandbox (or iframe for the UI layer), isolated from the kernel and other apps. An app has no direct filesystem or network access unless the manifest grants specific capabilities. Every call from the sandboxed app to the kernel is validated:

  • The operation name must exist in the manifest.
  • The arguments are type-checked.
  • The result is returned only if validation passes.

This model prevents untrusted or poorly written apps from:

  • Reading or writing arbitrary files.
  • Making unauthorized network requests.
  • Accessing other agents' memory or state.
  • Crashing the kernel itself.

Building Your First App

  1. Create the folder structure under apps/my-app/.
  2. Write manifest.json listing your operations and their signatures.
  3. Implement core.py with the logic, reading JSON requests from stdin and writing results to stdout.
  4. Create ui/index.html as the user interface, making calls to the kernel for each operation.
  5. Package as a .fwpack (the manifest and three files, compressed).
  6. Upload via the Apps menu → Install.

Once installed, the app is hot-loaded — no kernel rebuild, no restart. If you need to update the app later, uninstall and reinstall the new .fwpack.

The Principle: Write Once, Use Twice

The strength of Flowork's app model is that you don't write separate paths for "human UI" and "agent API." Instead:

  • The manifest declares what the app can do.
  • The headless logic (core.py) handles all cases.
  • The UI layer is thin — it calls the same operations a human would click.
  • Agents call the same operations programmatically.

This approach makes apps easier to reason about, test, and maintain. A bug fix in the logic fixes it everywhere; a new operation immediately becomes available to both humans and agents.

Flowork is open source — both products:

Top comments (0)