CompanyOS

CompanyOS is the next layer above a website, app, or merchant account. Each customer gets a bounded operating system of their own: a tenant identity, a runtime, a memory, a ticket inbox, a policy model, and a set of agents that can execute work inside that boundary.

QuantaLumin then operates as the upstream CompanyOS: the platform owner, support provider, specialist engineering team, and control plane for those customer systems.

Core model

• A CompanyOS is the tenant brain: identity, goals, knowledge, ticket history, policies, financial model, and operating memory.
• A LuminOS container is the execution boundary for that tenant: runtime profile, tools, storage, network, quotas, and audit hooks.
• Agents are role-bound workers inside the tenant, not global superusers.
• The ticket network is the protocol between CompanyOS tenants. Tickets are not just messages; they are executable work contracts with ownership, permissions, delivery state, writeback, and audit.
• The admin control dashboard is the operator surface for defining tenancy, policies, grants, runtime profiles, and support routing.

Execution boundary

The safe target is not “give a customer a shell on the whole platform”. The safe target is a per-tenant CompanyOS that can only execute through bounded surfaces.

The intended boundary is:

• Per-customer company or tenant boundary.
• Per-tenant container or k3s workload with no host mounts, no SSH, no pass, no Ansible, and no broad filesystem access.
• Repo-scoped Forgejo credentials only for that tenant’s repositories.
• Site-scoped and workspace-scoped signed tokens for generator actions.
• Tool allowlists per agent role.
• Full audit trail for every repo edit, publish, token mint, and approval.

QuantaLumin as the first CompanyOS tenant

QuantaLumin should dogfood this model on its own infrastructure first. The QuantaLumin codebase should move into a bounded operator LuminOS container so the platform owner no longer behaves like “the host with global access”. That operator runtime should become the reference CompanyOS tenant for how repositories, tools, tasks, and approvals are actually scoped.

The practical target is:

• quantalumin itself becomes a first-class CompanyOS tenant rather than an implicit host superuser.
• The QuantaLumin infrastructure source tree lives inside that tenant runtime as a bounded workspace rather than a host-global checkout.
• Shared platform work happens through scoped repo grants, subtree grants, tickets, and approvals rather than default host access.
• The operator tenant becomes the first place where the customer isolation model is proved in real daily use.

System agents by filesystem scope

Inside the QuantaLumin operator runtime, system agents should sit at explicit levels of the file structure rather than all operating at the same global scope.

The intended seating model is:

• org-root agents for cross-repo architecture, release policy, and shared runtime topology
• repo-root agents for one repository such as qluster, qluster-control, generator-api, payments, or a site source tree
• subsystem agents for one app, package, service, or content tree inside a repository
• site and workspace agents for one website, merchant, or content subtree only
• escalation and ticket handoff when work must cross repo or subtree boundaries

That means policy should not only answer “which repo can this agent touch?” It should also answer “which subtree can this agent touch, with which actions, and with whose approval?”

Ticket network

The ticket should become the unit of inter-company communication and execution.

Every ticket should carry:

• source tenant
• destination tenant
• service
• queue
• owner role
• owner agent
• allowed actions
• delivery state
• writeback history
• audit trail

That means a Rawson request should not merely become a QuantaLumin support row. It should become a ticket that originates in Rawson’s CompanyOS, routes into QuantaLumin’s CompanyOS, gets worked by the right specialist, and can then write back to Rawson’s CompanyOS with outcomes, requests, approvals, or follow-up tasks.

Control plane

The control plane should own the customer policy model rather than leaving it spread across inventory and host defaults.

The admin dashboard should control:

• which agents a tenant can use
• which tools each agent can call
• which Forgejo repos and branches they can touch
• which filesystem roots or subtrees each system agent can operate in
• which websites and workspaces they can edit or publish
• which actions are allowed: read, draft, submit, approve, publish, revert
• which LDAP, Keycloak, and Forgejo groups map to that tenant
• runtime profile, quotas, billing plan, and audit visibility

Inventory should remain as a transition aid, but long-term tenant policy should move into the control-plane data model, with Ansible reconciling from that source of truth rather than acting as the source of truth itself.

SphereList company view

A useful operator view for this system is a SphereList: a hybrid between a company map and an actionable queue list.

The point of the view is to let an operator move between structure and execution without changing mental models:

• start at the company
• step into a department sphere
• expand a role or agent seat
• see the owned tickets, workspaces, and current load in list form
• drill into the exact queue, ticket, or runtime that needs action

For QuantaLumin, that means the view should show departments such as leadership, engineering, operations, finance, sales, and brand, while also exposing the live list surfaces that matter for operating them: open tickets, blocked work, waiting-on-reply state, active runtimes, and owned repos or workspaces.

This should be a first-class control-plane surface, not just a decorative org chart. A sphere should always correspond to a real filterable list below it.

Question and answer

Question:

And this is safe enough that I could give web customers access to a subset of agents, and even containerise that company with access to specific Forgejo git repositories, so that they can modify their knowledge base, website and other repositories, without access to the whole, right? Moreover, perhaps the admin control dashboard should give me the ability to control and modify these attributes.

Answer:

The current pieces are close, but I would not yet give customers direct access with the live defaults.

• Two control-plane shortcuts still need tightening in Code/quantalumin/qluster-control/apps/api/src/server.ts:286 and Code/quantalumin/qluster-control/apps/api/src/server.ts:1451. If misconfigured, the control app falls back to henry, and dev mode grants the required role plus admin.
• generator-api already has the right scoped primitives, but they are still defaulted off in Code/quantalumin/generator-api/ops/prod-b1/generator.env.example:11. The enforcement logic already exists in Code/quantalumin/generator-api/api_utils/mcp_site_token and Code/quantalumin/generator-api/api_utils/trusted_principal.

The good news is that the design direction is correct.

• The control plane already knows the site’s repo, workspace, and publish target in Code/quantalumin/generator-api/control_plane/app.py:1100.
• It can mint site-scoped tokens in Code/quantalumin/generator-api/control_plane/app.py:2345.
• It already has owner and grant-based authorization in Code/quantalumin/generator-api/control_plane/app.py:2525.
• Forgejo-side org and repository mapping is already present in Code/quantalumin/qluster/scripts/reconcile_forgejo_directory_access.mjs:361.

So yes, you can get to customer company containers with access only to specific repos and sites safely, but only if customer agents go through these scoped APIs rather than through broad shell, git, or host access.

So the answer is: safe enough as a target architecture, not safe enough as-is. The next step is to flip customer-facing mutation flows onto enforced site-token and trusted-principal authorization, then put tenant policy management into the dashboard.

Implementation waves

Wave 1: Enforce scoped mutation boundaries

• Turn on customer-facing trusted-principal and site-token enforcement for generator mutations.
• Remove live fallbacks that collapse customer identity into broad developer or admin defaults.
• Ensure customer edit, draft, publish, and approval actions all route through scoped APIs rather than broad shell or host access.

Wave 2: CompanyOS tenant model

• Extend companyd so tenants become first-class CompanyOS records.
• Store tenant policy, runtime profile, tool allowlists, repo grants, subtree grants, site grants, and billing plan in control-plane data.
• Keep inventory as a deployment and reconciliation target rather than the long-term policy source of truth.

Wave 3: Tenant runtime containers

• Provision per-tenant LuminOS workloads in k3s with explicit quotas, network boundaries, and storage boundaries.
• Remove host-level assumptions from customer execution paths.
• Bind tenant runtimes only to the repos, sites, tools, and actions they are allowed to access.
• Dogfood the model by moving the QuantaLumin infrastructure codebase into its own operator LuminOS container with explicit repo and subtree boundaries for system agents.

Wave 4: Ticket federation and delivery

• Make tickets explicitly cross-tenant rather than only internal.
• Support ticket delivery, acknowledgement, ownership, writeback, and escalation across CompanyOS boundaries.
• Let support tickets auto-brief the assigned owner agent instead of stopping at ticket creation.

Wave 5: Dashboard policy and operator controls

• Add tenant management to the control dashboard.
• Expose agent, tool, repo, site, action, identity-group, runtime, quota, billing, and audit settings in one operator surface.
• Add approval gates for high-impact mutations such as publish, revert, and credential rotation.

Wave 6: Audit, recovery, and billing

• Record every token mint, repo edit, publish, approval, revert, delivery, and escalation.
• Add replayable audit views for operators and tenant-visible audit views where appropriate.
• Tie runtime profile, quotas, and feature access to billing plans and support contracts.

What customers should eventually experience

Each customer should experience their CompanyOS as:

• a bounded company workspace
• a support and operations brain for their website or business
• a secure place to evolve content, knowledge, pricing, processes, and tickets
• a way to request work from QuantaLumin through the ticket network
• a way to run their own approved agents inside their own execution boundary

QuantaLumin itself should use the same model internally: its own operator CompanyOS, its own bounded infrastructure workspace, and its own system agents seated at explicit filesystem scopes inside that runtime.

That is the end state: not a loose collection of apps, but a network of CompanyOS tenants running inside LuminOS containers, with QuantaLumin acting as the upstream operating company and also as the first serious dogfood tenant.