Skip to content
Scion

Web Dashboard Configuration

This document describes the configuration for the Scion Web Dashboard. The web UI is served by the Go scion binary with the --enable-web flag.

Purpose

Section titled “Purpose”

The Web Dashboard is a client-side SPA served by the Go server, which also handles OAuth, session management, SSE real-time events, and API routing. Configuration is managed through CLI flags and environment variables.

Server Flags

Section titled “Server Flags”
Flag Default Description
--enable-web false Enable the web dashboard.
--web-port 8080 The HTTP port the web UI listens on.
--session-secret (Deprecated — use the SESSION_SECRET environment variable instead.) Secret key for signing session cookies. Must be set in production. Passing secrets via CLI flags exposes them in /proc/pid/cmdline and ps(1) output; use the environment variable or a systemd EnvironmentFile for secure delivery.

Environment Variables

Section titled “Environment Variables”

Core Settings

Section titled “Core Settings”
Variable Default Description
SESSION_SECRET Secret key for signing session cookies. Preferred over --session-secret — environment variables are not visible in process listings. Deliver via systemd EnvironmentFile or a secrets manager.

Authentication

Section titled “Authentication”

OAuth Providers

Section titled “OAuth Providers”

These variables are required for standard user login in production.

Variable Description
SCION_SERVER_OAUTH_WEB_GOOGLE_CLIENTID Google OAuth 2.0 Client ID.
SCION_SERVER_OAUTH_WEB_GOOGLE_CLIENTSECRET Google OAuth 2.0 Client Secret.
SCION_SERVER_OAUTH_WEB_GITHUB_CLIENTID GitHub OAuth App Client ID.
SCION_SERVER_OAUTH_WEB_GITHUB_CLIENTSECRET GitHub OAuth App Client Secret.
SCION_SERVER_AUTH_AUTHORIZEDDOMAINS Comma-separated list of email domains allowed to sign in.

External OIDC Login Provider

Section titled “External OIDC Login Provider”

Configure user login via an external OIDC provider (e.g. Okta, Keycloak) in the server.oidc_login section of settings.yaml (enabled, display_name, issuer_url, client_id, client_secret, scopes). See Authentication for an example.

Underscored names such as SCION_SERVER_OIDC_LOGIN_ENABLED are ignored, and the Hub logs a warning at startup for each one. The collapsed names (SCION_SERVER_OIDCLOGIN_ENABLED, SCION_SERVER_OIDCLOGIN_ISSUERURL, and so on) take effect only when settings.yaml has a server: section. They are ignored on the legacy server.yaml path (ptone/scion#3038).

Development Authentication

Section titled “Development Authentication”

Used for local testing without setting up full OAuth.

Variable Default Description
SCION_DEV_TOKEN Explicit development token for Hub API access.
SCION_DEV_TOKEN_FILE ~/.scion/dev-token Path to the token file generated by the Hub.

Feature Flags

Section titled “Feature Flags”

Feature flags control the availability of Web Dashboard features. Registered experiments (see Experiments) are resolved in this order:

  1. Server value — the client fetches GET /api/v1/experiments at boot (signed-in users only). This is the hub-wide value an admin sets from Admin → Server Config → Experiments.
  2. localStorage override — set scion:feature:<name> in localStorage for development. Applies only to names the server did not send, or when the experiments fetch fails.
  3. Compiled default — flags listed below default to ON; all others default to OFF. Used when the experiments fetch fails.
Flag Default Description
web.native_chat ON Enable the Native Web Chat workspace.
web.terminal_workspace ON Enable the Terminal Workspace — a multi-pane terminal environment as a top-level workspace.
web.gcs_links OFF Linkify a gs://bucket/object URI an agent posts in chat, and let the viewer fetch and preview that object through the hub. Also gates the hub’s GET /api/v1/gcs/object endpoint, which additionally requires a configured GCP token generator.
hub.artifacts OFF Artifacts: files and bundles agents and users publish with stable, versioned references. Also gates the hub’s /api/v1/artifacts routes, which answer 404 while it is off, and the artifact page. See Artifacts.

web.terminal_workspace, web.gcs_links and hub.artifacts are registered experiments; web.native_chat is not (see Experiments for what that distinction means). web.native_chat is instead driven by the hub’s nativeChatEnabled setting (from /api/v1/settings/public): when it is false, boot writes the flag to false directly into the flag bag isFeatureEnabled checks first, ahead of any localStorage override.

To disable a registered experiment hub-wide, use the Experiments tab. A localStorage override has no effect on a registered experiment for a signed-in user on a working hub — it only applies to an unregistered flag (such as web.native_chat), or on a page load where the experiments fetch fails:

// localStorage override (development only; no effect on a registered
// experiment unless the experiments fetch fails)
localStorage.setItem('scion:feature:web.native_chat', 'false');

Security Settings

Section titled “Security Settings”

The Go server includes a pre-configured Content Security Policy (CSP) that allows connections to the Hub and necessary CDNs (Shoelace). HSTS is automatically enabled in production with a 1-year max-age.

Deployment

Section titled “Deployment”

The Web Dashboard is served by the same Go binary as the Hub API. In production, enable it with --enable-web and ensure the SESSION_SECRET environment variable and the OAuth provider variables are configured. Avoid passing the session secret via the --session-secret CLI flag, as CLI arguments are visible to other local users via /proc/pid/cmdline.