FlowaOS

An operating system for your agents — quiet, local, and entirely yours. FlowaOS runs on hardware you choose: a machine you already own, or one we provision for you. Either way it is your files, your network, your keys.

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

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.

Getting Started

Install the desktop app. On first run it opens on Connect this machine: sign in at the hub, then paste the pair code it mints into the app. Your first workspace is provisioned automatically, and the IDE opens on a working directory of your choice.

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)

Machine

A machine is a host that runs FlowaOS — either a cloud SKU we provision or hardware you own. One identity, N machines. The machine layer is where the daemon, PTY server, and tenant runtime live.

Both kinds are reached at username.flowaos.com and both appear in your machine picker. Self-hosting is a separate mode that opts out of all of that — see Self-host.

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 operator was instantiated from the library.

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.

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.

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 operator. Persisted by cwd hash at ~/flowaOS/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.

Flow Agents

A flow agent is an actor inside a flow. Either the synthetic operator (one per flow, bound to the flow's operatorId) 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.

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.

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.

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
• ·Operator / Claude / Super Claude — agent panels
• ·Voice — voice capture and transcription
• ·Team — collaborators
• ·Webviews — extension-hosted views
• ·Flow Agent — agent canvas

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.

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.

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.

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.

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.

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 ~/flowaOS/cwds/{cwdHash}/flows/{flowId}.json.

Theme

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

Enrollment

Enrolling a machine binds a desktop install to your identity through the hub. The app redeems a pair code, holds an outbound tunnel open, and heartbeats — after which the hub can route sessions to that machine.

Enrollment is what puts a machine in your registry and in your picker. A self-hosted install never enrolls.

Self-host

Self-host mode runs FlowaOS with no FlowaOS account and no hub in the path. The tenant serves directly from your machine; you own the address, the certificate, and the reverse proxy in front of it. Enable it from the app's Connect this machine screen: choose Self-host this machine rather than entering a pair code, then set a password — that password gates every session from then on.

This is not the same as running FlowaOS on a machine you own but paired to the hub. That machine is still reached at username.flowaos.com over our tunnel, and is called your machine throughout the dashboard.

What you provide

• ·A DNS A record for your domain, pointing at the machine’s public IP
• ·Inbound ports 80 and 443 forwarded to it — port 80 once, for the certificate
• ·A reverse proxy in front of the tenant’s local port; Caddy is the recommended path, for automatic HTTPS

Settings → Self-host generates the Caddyfile for the domain and port you enter, and walks the four steps in order. None of it is required to run locally: with no domain configured the app simply serves on its own port on the machine.