FlowaOSDocumentation

FlowaOS

An operating system for your agents — quiet, local, and entirely yours. FlowaOS runs on the hardware you already own, with your files, your network, your keys.

This documentation describes the architecture, surfaces, and modules of the system, and how to build inside it.

Coming soonThe detailed overview is being written. For now, browse the sections in the sidebar — each is structured to receive its content shortly.

Worldview

FlowaOS organises everything as a strict hierarchy. The user is rooted in an identity. Each identity has machines. Each machine has a single workspace at a time. A workspace owns desktops; each desktop hosts IDE tabs; each tab runs flows; each flow hosts flow agents.

Auth
  └── Machine
      └── Workspace
          └── Desktop
              └── IdeTab
                  └── Flow
                      └── FlowAgent

The ordering matters: scope always reads top-down. Anything that is workspace-wide is checked before anything desktop-wide; anything tab-bound is checked before anything flow-bound.

Coming soonFull worldview reference coming soon.

Getting Started

Install the desktop app, sign in through the hub, and your first workspace is provisioned automatically. From there the IDE opens on a working directory of your choice.

Coming soonStep-by-step install and first-run guide coming soon.

Hub

The hub is the public web entry point. It handles sign-in, identity, the tenant registry, and routing each authenticated session to the right machine.

Responsibilities

  • ·Authentication and identity for the user
  • ·Tenant registry — which machines an identity owns
  • ·Routing — handing the session off to a desktop or hosted tenant
  • ·Marketing surface for new visitors (the landing page)
Coming soonDetailed hub reference coming soon.

Machine

A machine is a host that runs FlowaOS — either a cloud SKU or a self-hosted box. One identity, N machines. The machine layer is where the daemon, PTY server, and tenant runtime live.

Coming soonMachine model, lifecycle, and identity binding coming soon.

Workspace

A workspace is the authoritative profile on a machine. It owns user preferences and its desktop set. Switching workspace switches the entire mental space — wallpaper, persona, layout, the lot.

The Assistants library is identity-level, not workspace-level. A flow points at one library entry through Flow.assistantSourceId when its synthetic assistant was instantiated from the library.

Coming soonWorkspace switching, prefs, and persistence detail coming soon.

Desktop

A desktop is a runtime surface inside a workspace. It owns the canvas, window arrangement, and IDE tab set. A workspace can have many desktops; one is active at a time.

Coming soonDesktop model and window manager detail coming soon.

IDE Tab

An IDE tab is an IDE session bound to a working directory. It owns the cwd plus IDE shell state: columns, grid, panes, modules, file selection, editor buffers. Many tabs per workspace, one active at a time.

The cwd determines which files, repos, tools, and flows are in scope. cwdAtom is derived from the active tab.

Coming soonIDE tab lifecycle, grid/pane model, and module mounting coming soon.

Flows

A flow is a unit of work over the cwd. It owns its FlowAgent canvas, queue and event bus, expectations, memory, and a pointer to a synthetic assistant. Persisted by cwd hash at ~/.flowa/cwds/{cwdHash}/flows/{flowId}.json.

Many flows per cwd, one active at a time. The activeFlowId pointer is workspace-global, not stored on Desktop or IdeTab.

Coming soonFlow lifecycle, queue, and restorability semantics coming soon.

Flow Agents

A flow agent is an actor inside a flow. Either the synthetic assistant (one per flow, bound to the flow's assistantId) or a user-spawned agent on the canvas.

Each owns position, transcript, and CLI worker bridge, and addresses peers as a cluster of brain (unitId) and worker (unitId:cli) over the queue.

Coming soonAgent canvas, addressing, and message bus coming soon.

Assistants

The Assistants library is identity-level state stored in Firestore at users/{uid}/assistants/*. A flow instantiates one assistant from the library; mutations on the instance do not flow back to the library entry.

Coming soonAuthoring assistants, persona, and library management coming soon.

Agent Daemon

The agent daemon is the long-running process on a machine that hosts flow agents, brokers their queues, and keeps PTY sessions alive across UI restarts. It is the bridge between the desktop shell and the running work.

Coming soonDaemon lifecycle, restart semantics, and IPC coming soon.

Modules

Modules are the pluggable surfaces that mount inside an IDE tab's grid. Each module is independently mountable, focusable, and resizable, and is registered through the module registry.

Built-in modules

  • ·Editor — code surface backed by Monaco
  • ·Terminal — PTY-backed shell
  • ·Filetree — workspace file browser
  • ·Git — staging, diff, branches
  • ·Search — workspace-wide search
  • ·Logs — structured log stream
  • ·Problems / Output / Tests — VS Code-style problem and test surfaces
  • ·Debug — console, stack, variables, watch, launch
  • ·Notebook — runnable cells
  • ·Extensions — installed extension manager
  • ·Assistant / Claude / Super Claude — agent panels
  • ·Voice — voice capture and transcription
  • ·Team — collaborators
  • ·Webviews — extension-hosted views
  • ·Flow Agent — agent canvas
Coming soonPer-module documentation coming soon.

Editor

The editor module hosts Monaco bound to the active IdeTab's cwd. Multiple editor panes can be open in a single tab's grid; each tracks its own buffer and selection.

Coming soonEditor model, buffer management, and selection sync coming soon.

Terminal & PTY

Terminal modules embed xterm.js connected via WebSocket to a PTY daemon on the machine. Each terminal is a real pseudo-terminal with full colour and interactivity, and survives UI restarts.

Coming soonPTY daemon, session resume, and bridge interface coming soon.

Git

The git module reflects the active cwd's repository — staging, diffs, branches, and commit graph. Operations route through the machine's real git, not a re-implementation.

Coming soonGit module reference coming soon.

Extensions

FlowaOS supports VS Code extensions through Open VSX. Phase 3 of the extension host is on the critical path for full .vsix compatibility, including terminals, trees, and webviews.

Coming soonExtension host, capability surface, and install flow coming soon.

Voice

The voice module captures audio, transcribes it, and routes the result to the active assistant. It is mountable as a module inside an IDE tab.

Coming soonVoice pipeline, models, and key bindings coming soon.

Persistence

FlowaOS persists state in three places: identity-level Firestore (assistants, profile), per-machine local state (workspaces, desktops, IDE tabs), and per-cwd flow files at ~/.flowa/cwds/{cwdHash}/flows/{flowId}.json.

Coming soonFull persistence map and restorability guarantees coming soon.

Theme

Themes are workspace-level. Switching workspace switches the wallpaper, palette, and persona of the desk.

Coming soonTheme tokens and authoring coming soon.

Enrollment

Enrolling a machine binds a desktop install to your identity through the hub. After enrollment the hub can route sessions to that machine.

Coming soonEnrollment flow and key handling coming soon.

Building Modules

Modules are registered in apps/tenant/app/modules/registry.ts. A module is a React component plus a registry entry that declares its id, title, icon, and default sizing.

Coming soonModule authoring guide — component shape, registry entry, persistence hooks — coming soon.

Running Locally

FlowaOS is a monorepo of apps (hub, desktop, tenant, mobile, services) and shared packages (agent-daemon, shared). Local dev runs the hub, the tenant, and the agent daemon side-by-side.

Coming soonLocal dev setup, ports, and credential bootstrap coming soon.