Shell Integration

Build and run shell_federated apps on Groundfloor with Keycloak auth and Control Plane APIs.

Audience: Shell host team and federated remote app developers
Last updated: 2026-05-29 · Phase 3 (complete)

These guides explain how to build and run shell_federated apps on Groundfloor: bootstrap the Shell host, authenticate with Keycloak, and call Control Plane pillar APIs (vault, files, secrets, LLM, and more).

Architecture (one page)

Account (billing org)
  └── Workspace (UUID — your tenant boundary)
        └── App (slug, manifest, releases)
              └── Federated remote (remoteEntry.js in object store)

Layer	Owner	App developer calls it?
Shell host (Next.js + Module Federation)	Shell repo	Loads bootstrap + remote
App manifest + publish metadata	Control Plane Postgres	Via public bootstrap API
Built UI (`remoteEntry.js`)	Object store (S3/MinIO)	Browser loads `manifest.remoteUrl`
Customer data (collections, queries)	Dataplane	No — use Control Plane `/vault` proxy
Secrets, files, LLM keys	Control Plane + Infisical / LiteLLM	Yes — workspace-scoped APIs

Rule: Federated apps call Control Plane at /v1/workspaces/{workspace_id}/…. Do not call Dataplane directly from the browser.

Reading order

New here? Start with 01-getting-started.md.

#	Document	Who	Purpose
01	Getting started	Both	End-to-end tutorial: register → build → publish → load
02	Shell bootstrap (quick reference)	Shell host	Env vars, bootstrap URL, MF wiring
—	Shell bootstrap (full guide)	Shell host	Complete integration reference
03	Authentication (Keycloak)	Both	Platform JWT, permissions, wiring in Shell/remote
08	Shell auth modes	Shell host	End-user sign-in: `none` / `groundfloor` / `external` discovery + wiring
13	Workspace site auth (agent prompt)	Shell team	Copy-paste Cursor task for workspace OIDC + D-045 tokens
14	Groundfloor E2E — CP side	Shell + ops	Prerequisites, curl test plan, troubleshooting
04	Data Vault	App	Collections, query, CRUD via Control Plane
05	Files	App	Presigned upload/download lifecycle
06	Secrets	App / backend	List, reveal, upsert workspace secrets
07	LLM Gateway	App	Virtual keys, LiteLLM, model catalog
09	Manifest and routes	Both	Manifest contract, slug vs appId, publish
10	API reference index	Both	OpenAPI, tags, `@groundfloor/api-client`
11	Local dev recipes	Both	Copy-paste curl and fetch examples
12	Troubleshooting	Both	Common errors and fixes
—	Shell agent prompt	Shell team	Copy-paste task for Cursor agent in `groundfloor-v2.5`

Machine-readable API contract

Resource	Location
OpenAPI (running server)	`{CONTROLPLANE_URL}/docs`
OpenAPI JSON (committed)	`apps/customer/openapi.json` (regenerate: `uv run python scripts/sync_openapi.py`)
TypeScript client	`@groundfloor/api-client` (orval + TanStack Query hooks)

See 10-api-reference.md for codegen workflow.

Identity provider

Control Plane and the Customer Portal use Keycloak (IDP_PROVIDER=keycloak). Clerk is legacy only.

Shell and federated remotes should obtain a platform Keycloak access token and send Authorization: Bearer {token} on authenticated Control Plane calls. See 03-authentication.md.

Syncing docs to the Shell repo

From the Control Plane repo root:

./scripts/sync_shell_federated_docs.sh

Set SHELL_REPO to override the default (../groundfloor-v2.5). The script copies this folder plus the full bootstrap guide into the Shell monorepo (and starter-kit bundle when that directory exists).

Shell agent kickoff

Open groundfloor-v2.5 in Cursor and paste:

Implement the Control Plane federated app integration task in docs/controlplane/SHELL_AGENT_PROMPT.md (Phase A through D). Read the linked controlplane docs first. My workspace UUID is {WORKSPACE_ID} and my app slug is {APP_SLUG}. Control Plane is at http://localhost:8088. Do not remove legacy BaaS/COI paths; gate them when CP env is set.

Replace {WORKSPACE_ID} and {APP_SLUG} with your values.

Support references

Topic	Control Plane location
Phase 1 federated plan	`docs/plans/federated-shell-apps-phase1.md`
Manifest validation	`app/domain/entities/shell_manifest.py`
Bootstrap routes	`app/api/routers/app_shell.py`
Portal bootstrap UI	`apps/customer/src/components/apps/shell-bootstrap-card.tsx`
Phase 2 deps (MinIO, Infisical, LiteLLM)	Phase 2 deps runbook