Building Custom Surfaces

Corral’s built-in surfaces — the Hub, Admin Console, Teams, and embedded widget — cover the most common interaction patterns. But enterprises and partners often need custom UIs: branded portals, domain-specific dashboards, embedded AI in existing applications, or entirely novel interaction paradigms.

Corral is designed for this. The platform is API-first, and every surface (including the ones we build) uses the same APIs and protocols you’d use to build your own.

The Architecture

Every Corral surface communicates with the platform through two channels:

REST API — for management operations (configuration, publishing, analytics, permissions)
DirectLine WebSocket — for real-time agent messaging (sending messages, receiving streamed responses, tool call updates)

Your custom surface uses the same channels. Authenticate with client credentials (Management or Consumer scope), connect to DirectLine for messaging, and call the REST API for everything else.

The Control Room as Reference Implementation

The Control Room (Corral.Clients.ControlRoom) is an internal development tool being built out as an exemplar custom frontend. It demonstrates how to use Corral agents as a backend for a completely custom UI — in this case, data visualization and project management interfaces powered by AI.

[PLACEHOLDER FOR SECTION: When the Control Room is further along, document it as the reference implementation. Show the architecture: Svelte frontend → DirectLine for AI messaging → REST API for platform operations. Include code examples of connecting to DirectLine, sending messages, and handling streamed responses.]

Getting Started

1. Create Client Credentials

Create credentials with the Consumer scope for your custom surface:

POST /api/apps/{slug}/client-credentials

See Client Credentials & OAuth →.

2. Connect to DirectLine

DirectLine is the real-time messaging protocol that powers all Corral chat interfaces. Your custom surface opens a WebSocket connection and exchanges messages with the agent.

[PLACEHOLDER FOR SECTION: DirectLine connection flow — how to get a DirectLine token from the API, how to establish the WebSocket, message format for sending user messages, and the event format for receiving agent responses (including streamed text, tool call notifications, and file system events).]

3. Handle Agent Events

Beyond chat messages, agents emit events your surface can react to:

File changes — when the agent creates or modifies files in the workspace
Canvas content — charts, diagrams, and generated UI
Tool call status — which tools are being invoked and their results
Taint transitions — when the conversation’s trust level changes (CRF Phase 2+)

4. Call the REST API

For management operations — reading configuration, pulling analytics, managing permissions — use the REST API with Management-scoped credentials.

See API Reference →.

Frontend Stack (If Building on Corral’s Shared Components)

Corral’s own surfaces are built with:

Svelte 5 (runes: $state, $derived, $effect)
shadcn-svelte via bits-ui
Tailwind CSS 4
@microsoft/signalr for real-time events
@xyflow/svelte for flow diagrams
layerchart for data visualization

The shared component library (clients/shared-assets/) includes chat components, workspace panel, auth context, and state managers. If you’re building a Svelte surface, you can use these directly.

You’re not required to use Svelte. The API and DirectLine protocol are framework-agnostic — build with React, Vue, Angular, or vanilla JavaScript.