PilotSwarm Portal Builder

Build browser portal experiences on top of the shipped PilotSwarm web portal.

Canonical References

• Source quickstart: https://github.com/microsoft/PilotSwarm/blob/main/docs/quickstart/local.md
• Portal guide: https://github.com/microsoft/PilotSwarm/blob/main/packages/app/web/README.md
• SDK guide: https://github.com/microsoft/PilotSwarm/blob/main/docs/developer/building/sdk-apps.md
• Plugin architecture: https://github.com/microsoft/PilotSwarm/blob/main/docs/developer/building/plugins.md
• AKS deployment: https://github.com/microsoft/PilotSwarm/blob/main/docs/developer/deploy/aks.md
• DevOps sample: https://github.com/microsoft/PilotSwarm/tree/main/examples/devops-command-center

Personal multi-session workspaces

The shipped portal includes Master of Agents (MoA): up to five personal chat/canvas dashboards, split panels, a shared focused composer, and focus mode. It uses the same branding and session permissions. No plugin setting is needed. Desktop tabs can be reordered, with order and layouts saved in the user profile. Visited views are cached only in browser memory and refresh only while visible. Mobile shows one panel at a time, a proportional panel map, and a triangle-only dashboard picker in the session header; it does not support tab dragging. MoA has no sharing links and is unavailable in the native TUI. See docs/user-guide/master-of-agents.md for behavior and keyboard controls.

Preferred Structure

my-app/
├── plugin/
│   ├── plugin.json
│   ├── assets/
│   ├── agents/
│   └── skills/
├── deploy/
│   ├── Dockerfile.portal
│   └── k8s/
│       └── portal-deployment.yaml
├── scripts/
│   └── run-portal.sh
└── README.md

Workflow

1. Run a guided intake before scaffolding.
2. Prefer plugin.json.portal for browser branding and sign-in copy.
3. Use plugin.json.tui as a fallback or shared source only when the user wants the portal and TUI aligned.
4. Make named-agent availability explicit by packaging the app plugin for the portal process.
5. If the portal is deployed remotely, wire PLUGIN_DIRS in the portal environment.
6. Treat authentication as a provider-based add-on, not a built-in Entra assumption.
7. If auth is enabled, separate browser sign-in UX, token acquisition, and server-side validation clearly.
8. Add local launch guidance and remote rollout guidance that match the actual repository layout.

Guided Intake Questions

Before generating files, ask:

1. What should the portal be called?
2. Should the portal reuse the TUI title and splash, or have its own branding?
3. What logo asset should the portal use?
   • ask for a checked-in path such as plugin/assets/logo.svg
   • ask whether the browser tab icon should reuse that same asset or use a separate favicon
4. Which named agents should be creatable from the portal?
5. Which auth provider should the portal use?
   • none
   • entra
   • another provider described by the user
6. If auth is enabled, what should the sign-in title and helper copy say?
7. Will the portal run locally only, or also in AKS / remote deployment?

Do not guess these answers when they materially affect the scaffold. If the user wants a fast default, offer:

• matching TUI + portal branding
• a shared portal logo at plugin/assets/logo.svg
• generic sign-in copy
• none or entra for auth
• plugin-driven packaging with PLUGIN_DIRS

Web API Guidance

• The portal server hosts the deployment's Web API (/api/v1 + WS) — the single surface every client rides (browser UI, TUI remote, SDK apps, MCP, custom UXes on pilotswarm-sdk/api).
• Named agents reach all clients via GET /api/v1/bootstrap (creatableAgents); that is why portal images must package the app plugin and set PLUGIN_DIRS.
• Validate a portal rollout with GET /api/v1/health and GET /api/v1/auth/config.

Portal Config Guidance

• Put browser-specific branding under plugin.json.portal.
• Prefer nested portal config: portal.branding, portal.ui, and portal.auth.
• Keep page title, splash text, loading copy, and sign-in copy in plugin metadata instead of hardcoding them into app code.
• Keep the logo path in plugin metadata so the splash screen, signed-in header, and browser tab icon stay in sync.
• Use plugin.json.tui only when the user explicitly wants the same title/splash across TUI and portal.
• Keep agent prompts and personas in plugin/agents/*.agent.md, not inside portal UI files.
• Every generated .agent.md must include schemaVersion: 1 and a version string. Use version: 1.0.0 for new agents by default, and bump version when editing an existing agent's prompt behavior, tools, workflow guidance, or metadata.
• Use session-policy.json when the user wants the portal to offer only a curated agent roster instead of generic sessions. To expose SDK-bundled optional agents such as the generic crawler, add "bundledAgents": ["generic-crawler"] under creation; the portal bootstrap must see that policy through PLUGIN_DIRS so creatableAgents includes the bundled agent.

Example:

{
  "name": "waldemort",
  "description": "Operations workspace",
  "portal": {
    "branding": {
      "title": "Waldemort",
      "pageTitle": "Waldemort Portal",
      "logoFile": "./assets/logo.svg",
      "faviconFile": "./assets/favicon.png"
    },
    "ui": {
      "loadingMessage": "Preparing your command center"
    },
    "auth": {
      "signInTitle": "Sign in to Waldemort",
      "signInMessage": "Use your organization account to open the browser workspace."
    }
  }
}

Logo notes:

• branding.logoFile is the preferred checked-in asset path
• the same logo is used on the loading splash, sign-in gate, signed-in header, and browser tab icon unless branding.faviconFile overrides it
• keep logo assets inside the plugin directory so the remote portal image can package them with plugin.json

Auth Guidance

• Treat none as a valid first-class choice.
• Keep auth provider selection explicit with PORTAL_AUTH_PROVIDER.
• For the shipped Entra provider, document:
  • PORTAL_AUTH_PROVIDER=entra
  • PORTAL_AUTH_ENTRA_TENANT_ID
  • PORTAL_AUTH_ENTRA_CLIENT_ID
  • PORTAL_AUTHZ_ADMIN_GROUPS / PORTAL_AUTHZ_USER_GROUPS as comma-delimited email allowlists when admission gating is requested
  • redirect URI registration for the portal host
• Use only the canonical PORTAL_AUTH_* and PORTAL_AUTHZ_* env vars; do not document or scaffold legacy ENTRA_* fallbacks.
• If the user wants another provider such as AWS IAM, do not force Entra-specific language into the scaffold.
• For custom providers, separate:
  • browser-side sign-in initiation
  • token acquisition/storage
  • server-side request validation

Local And Remote Launch Guidance

• For local usage, prefer a checked-in script such as scripts/run-portal.sh.
• Local launch guidance should use pilotswarm-web --plugin ./plugin or the equivalent app wrapper.
• For remote deployments, package the app plugin into the portal image or mount it into the portal pod.
• Set PLUGIN_DIRS in the portal deployment so the web process can resolve:
  • plugin.json.portal
  • plugin.json.tui
  • plugin/agents/*
  • session-policy.json
• When session-policy.json.creation.bundledAgents is used, verify the portal bootstrap exposes the bundled agent in creatableAgents; seeing the worker log Loaded: ... generic-crawler is not sufficient for the browser picker.
• When documenting Kubernetes secrets for portal settings, prefer kubectl create secret generic ... --from-env-file=... for env files that may contain shell-significant characters.

Validation Guidance

• For opt-in live reasoning/answer previews, set PILOTSWARM_LIVE_TURN=1 on workers (also the portal for embedded local workers). Use the shipped live plane and shared UI; do not persist raw deltas or create a parallel chat stream. Custom clients should follow docs/architecture/live-plane.md and keep durable event replay authoritative.
• Do more than write files: run a local portal build when practical.
• Verify the portal can load branding from plugin.json.portal.
• Verify named-agent creation appears in the browser UI when the plugin and session policy are present.
• If auth is enabled, verify the portal-config/bootstrap path advertises the selected provider correctly.
• For remote deployments, verify GET /api/health and GET /api/portal-config against the live ingress host.

Guardrails

• Do not hardcode PilotSwarm branding into app-specific portal code when plugin metadata can drive it.
• Do not assume the portal can infer named agents from remote workers alone.
• Do not assume Entra ID is mandatory.
• Do not invent app-specific auth protocols when the user really wants auth disabled.
• Keep portal UX copy, prompt layers, auth wiring, and deployment packaging as separate concerns.