The Filesystem Is the Platform

The most important interface in llumos is not a dashboard, a database, or a remote API. It is a folder.

That sounds almost too plain to be architecture. But plainness is the point. The filesystem is the one substrate every real computer already understands: files can be read, edited, diffed, built, launched, backed up, zipped, synced, inspected, deleted, restored, and moved. Agents are very good at reasoning over that kind of world because it is explicit. Nothing is hidden behind a product team's private service boundary.

In llumos, an app is not a row in somebody's hosted database. It is a real project directory. The orchestrator does not need a special internal API to understand your ecosystem. It can walk the tree, open files, read manifests, inspect source, patch integration code, run builds, and see the same artifacts a developer would see.

What llumos puts on disk

The current llumos app manager starts with an apps root directory. Locally that defaults to a folder on your machine, and users can choose another location in settings. Inside that root, every generated app gets its own directory: <apps-root>/<app-id>/.

The app registry is a small JSON file named .llumos-apps.json. Each app directory holds the generated React and Vite project, its build output, and its local state. User data written through window.llumos.store lands in .llumos-store.json inside that app's folder. Chat history and per-app memory live under .llumos/. The global system keeps settings, timeline, learned patterns, and message contracts in ordinary files under the llumos home directory.

There is no mystery layer here. The architecture is inspectable because the architecture is files.

Why not start with a database?

A database is usually the default answer once software gets serious, and for good reasons: query performance, transactions, indexes, permissions, analytics, concurrent writes. But llumos is not currently trying to coordinate millions of rows across thousands of users. It is trying to let an agent build, inspect, modify, launch, and connect personal apps that already exist as files.

Adding a database too early would move the important state out of the same world the agent is already operating in. Now the orchestrator needs schemas, migrations, seed data, connection strings, credentials, backups, service startup, version compatibility, query conventions, and a second permission model. For a local-first app ecosystem, that is a lot of machinery before it has earned its keep.

It also widens the security surface. A local file is protected mostly by the operating system's filesystem permissions and by the scope rules llumos gives the agent. A database often adds a long-running process, auth secrets, network bindings, SQL or document-query injection risk, migration failure modes, and multi-tenant access questions. Those are solvable problems. They are also problems you should choose on purpose, not inherit because "real apps use databases."

So the tradeoff is not files versus databases forever. It is files first, because files keep the system portable, inspectable, cheap to run, easy to back up, and easy for agents to reason about. A database becomes the right tool when the problem stops looking like "a personal app ecosystem on one machine" and starts looking like "many users, many writers, large indexed datasets, or strict audit requirements."

Why the orchestrator works

llumos has two scopes. A workspace agent is pointed at one app directory and told to stay there. It builds, edits, validates, and improves that one app. The orchestrator is pointed at the apps root and given permission to read and write across app subdirectories. That one difference changes everything.

Because every app is laid out as source code on disk, the orchestrator can treat an ecosystem as a set of sibling projects. It reads the app manifest, sees each app's path, understands their state shapes, adds window.llumos.send() to one app, adds window.llumos.onMessage() to another, persists incoming data with window.llumos.store, rebuilds both apps, then scans contracts so the next orchestration pass starts with more knowledge than the last one had.

That gives the orchestrator native access in the useful sense: it can operate on the real materials of the system. Source files, package files, build artifacts, logs, stores, contracts, and memory are all first-class things it can inspect and change.

Why local and cloud can be the same architecture

The filesystem model is also why a cloud version does not need a different mental model. Locally, the apps root might be somewhere on your laptop. In the cloud, it can be a mounted volume on a virtual machine. The orchestrator does the same job either way: run inside an environment, read the apps root, modify files, run builds, and launch or serve the result.

That is a much cleaner split than "local app" versus "cloud app." llumos can be local-first without making the implementation parochial. The unit of ownership is the directory. Put that directory on your Mac and llumos feels native to your computer. Put it on a VM and the same agent loop can power a hosted workspace. The storage primitive did not change. Only the machine changed.

That matters because it keeps the orchestrator honest. It cannot rely on secret platform state that only exists in one deployment. If a thing matters, it has to be represented in files the agent can recover from: a manifest, a contract, a timeline event, a memory entry, a source file, a build artifact.

Why this points toward operating systems

If the long-term goal is agents that help design at the operating-system level, then the filesystem is not an implementation detail. It is the training ground.

Operating systems are not just UI surfaces. They are permissions, processes, files, windows, events, stores, defaults, paths, build products, background jobs, and human habits that accumulate over time. An agent that only knows how to call a SaaS API is not ready for that world. An agent that can reason through a live filesystem, respect scope boundaries, connect running apps, preserve user data, and leave behind durable context is much closer.

That is where llumos wants to go: from "make me an app" to "help me shape the software layer of my computer." The app directory is the small unit. The apps root is the ecosystem. The orchestrator is the coordination layer. The filesystem is the shared reality underneath all of it.

So yes, llumos runs on folders. That is the magic trick. The folder is portable, inspectable, durable, and already native to every machine we care about. Build the agent around that, and the path from local app creation to cloud workspaces to OS-level design becomes one continuous architecture.