Skip to content
KSail

Web UI & Desktop App

KSail ships one web UI that runs in three places: locally in your browser, as a native desktop window, or inside a cluster served by the KSail operator. All three talk to the same REST API, so the experience is identical — pick the surface that fits how you work.

flowchart LR
    UI["🖥️ KSail Web UI"]

    UI --- Local["ksail open web<br/>local server · 127.0.0.1"]
    UI --- Desktop["ksail open desktop<br/>native window"]
    UI --- Operator["KSail operator<br/>in-cluster · OIDC optional"]

    Local -->|"REST API"| Docker["🐳 Local clusters via Docker"]
    Desktop -->|"REST API"| Docker
    Operator -->|"REST API"| CRs["☸️ Cluster custom resources"]

    style UI fill:#2ec4e622,stroke:#2ec4e6
    style Local fill:#10b98122,stroke:#10b981
    style Desktop fill:#10b98122,stroke:#10b981
    style Operator fill:#7c3aed22,stroke:#7c3aed

Choosing a Surface

Section titled “Choosing a Surface”
Surface Command Best for
Browser ksail open web Quick visual management of local clusters without installing anything extra
Desktop app ksail open desktop A dedicated window outside the browser, launchable from your dock
In-cluster Helm chart with ui.enabled=true Team-shared dashboards over operator-managed clusters, with optional OIDC sign-in

Running Locally

Section titled “Running Locally”

ksail open web starts a small local web server and opens the UI in your browser. The server binds to 127.0.0.1 only — it is never exposed to your network — and serves both the UI and a REST API backed by your local cluster lifecycle. It runs until you press Ctrl+C.

Terminal window
ksail open web              # pick a free port and open the browser
ksail open web --port 8080  # serve on a fixed port
ksail open web --no-browser # start the server without opening a browser

This is the same UI the KSail operator serves in-cluster, but here it provisions and manages clusters locally via Docker.

Install on iPhone or iPad

Section titled “Install on iPhone or iPad”

You can add the UI to an iPhone or iPad Home Screen, or to the Dock on a Mac, and open it in its own window with the KSail name and icon, like an app.

To reach it from a phone or tablet, serve it from the cluster: install the KSail operator with ui.enabled=true, expose the UI through the chart’s Ingress, and turn on OIDC sign-in so only signed-in users can reach the API. Securing with OIDC shows the settings.

  1. Open the UI’s address in Safari and sign in.
  2. Tap Share, then Add to Home Screen. On a Mac, choose File → Add to Dock.

The installed app shows live cluster state, so it needs a connection to the operator. Nothing is cached for offline use.

Read-Only Mode for GitOps

Section titled “Read-Only Mode for GitOps”

In GitOps-enforced environments the Git repository should stay the single source of truth. Deploy the in-cluster UI with ui.readOnly=true to lock it to inspection: the restriction is enforced server-side by the REST API, not just hidden in the frontend.

CLI Reference

Section titled “CLI Reference”

ksail open web, ksail open desktop

Section titled “Related”