loco-admin-web/specs/designs/00-foundation/multi-tenancy.md

Multi-Tenancy

Overview

Agent PaaS is scoped by workspaces. A workspace is an isolated configuration and deployment environment: it has its own persistence backend (where CR YAML files are stored) and its own deployment target (the Kubernetes cluster or namespace where agents run). All catalog reads/writes and all live resource queries are routed to the active workspace.

Workspace

A workspace has two independent dimensions:

Persistence

Determines where CR YAML files are stored and how mutations are committed.

Type	Fields	Description
local	directory, authorName, authorEmail	Local filesystem repo via isomorphic-git
git	repoUrl, branch	Remote Git repository (GitHub)

Both types accept optional directory overrides in WorkspacePersistence (for example modelsDirectory, toolsDirectory, kbsDirectory, and agentsDirectory). In the current implementation, catalog constructors still use their built-in default directories.

The local type writes commits directly to the filesystem; mutations are auto-committed and the PR lifecycle is skipped. The git type writes via pull request; the PR may be auto-merged based on policy.

Deployment

Determines where live runtime status is read from.

Type	Fields	Description
k8s	namespace, apiUrl?, token?, skipTlsVerify?	Kubernetes API server (in-cluster or remote)
local	—	No-op; no live status available

Server Initialization

At startup, Server.init() reads the workspace list and constructs one Catalog and one Resources instance, each internally keyed by workspace ID:

Server.init()
  → Catalog(workspaces)   — one GitClient + WorkspaceCatalog per workspace
  → Resources(workspaces) — one K8sClient + WorkspaceResources per workspace (k8s only)

Both are fully initialized before the first request is served. Workspace configuration is managed by WorkspaceManager (accessed via server.ws); current implementation returns a single local workspace (default).

Workspace Selection

Cookie

The active workspace is stored in the workspaceId cookie (path: '/'). On each request, hooks.server.ts reads this cookie into event.locals.workspaceId.

Default Selection

+layout.server.ts calls server.ws.list() on every page navigation and returns the full list to the frontend. It validates the current workspaceId cookie against both the workspace list and the user's permitted workspaces (user.workspaces). If invalid or absent, it resets the cookie to the first workspace in the list.

Workspace Selector UI

The workspace selector displays all workspaces the current user has access to and indicates the active one. Selecting a workspace writes the workspaceId cookie and reloads the current page.

Request Flow

Browser request
  → hooks.server.ts
      reads session cookie      → locals.user
      reads workspaceId cookie  → locals.workspaceId

  → route handler / load function
    server.catalog.getWorkspaceCatalog(locals.workspace.id)     → catalog ops
    server.resources.getWorkspaceResources(locals.workspace.id) → resource queries

If the workspace is absent or does not match any configured workspace, getWorkspaceCatalog / getWorkspaceResources throw NotFoundError.