Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt

Use this file to discover all available pages before exploring further.

​
Dashboard Authentication

Protect the CCS dashboard with optional username/password authentication. Authentication is still disabled by default, but the remote-access behavior is now much clearer than older CCS releases.
CCS does not ship a default dashboard username or password.
Enable dashboard auth whenever the bind is reachable from another device, including when you run ccs config --host 0.0.0.0.

​
Access Modes

SituationWhat users see
Localhost access, auth disabledDashboard opens normally without login
Remote/IP access, auth disabledDashboard UI can open, but sensitive management routes stay localhost-only
Remote/IP access, auth enabled but incompleteLogin page shows a setup-state message instead of a misleading blank sign-in form
Remote/IP access, auth enabled and configuredFull authenticated dashboard access
When auth is disabled, remote users can still inspect read-only dashboard surfaces, but write-capable routes stay locked to localhost until the host owner runs ccs config auth setup.

​
Quick Setup

ccs config auth setup
ccs config auth show
ccs config
The setup wizard:
  • prompts for username and password
  • hashes the password with bcrypt before saving
  • writes the result into ~/.ccs/config.yaml
  • preserves credentials if you later disable auth and want to re-enable it

​
Manual Configuration

dashboard_auth:
  enabled: true
  username: admin
  password_hash: "$2b$10$your-bcrypt-hash-here"
  session_timeout_hours: 24
Environment variables override config.yaml.

​
Login Flow

When authentication is enabled:
  1. Open the dashboard URL printed by ccs config
  2. If auth is configured correctly, CCS redirects you to the login page
  3. Enter username and password
  4. On success, CCS returns you to the original destination
  5. The session persists for the configured timeout (24 hours by default)
The login page also makes the host setup state explicit for remote users, includes a show/hide password control, and exposes a theme switch before sign-in.

​
Remote Read-Only Fallback

When auth is disabled and the dashboard is reachable beyond localhost:
  • remote users can still open read-only dashboard views
  • sensitive management routes stay localhost-only
  • AI Provider management, CLIProxy auth/status helpers, and other write-capable endpoints reject non-loopback requests
This means you can inspect the dashboard remotely without silently opening full management access.

​
Configuration Reference

KeyTypeDefaultDescription
enabledbooleanfalseEnable or disable dashboard login
usernamestring""Login username
password_hashstring""Bcrypt password hash
session_timeout_hoursnumber24Session lifetime in hours

​
Environment Variables

VariableMaps to
CCS_DASHBOARD_AUTH_ENABLEDdashboard_auth.enabled
CCS_DASHBOARD_USERNAMEdashboard_auth.username
CCS_DASHBOARD_PASSWORD_HASHdashboard_auth.password_hash
CCS_SESSION_SECRETCustom session encryption key

​
Security Notes

  • CCS uses HTTP-only session cookies instead of localStorage
  • Login attempts are rate-limited
  • Passwords are stored as bcrypt hashes
  • Remote write access fails closed when auth is disabled

​
Troubleshooting

​
Remote users see setup guidance instead of a login form

That means auth is enabled or intended, but the host has not finished configuration. Run: 
ccs config auth setup
If you are on the same machine, reopen the localhost dashboard URL instead of the network URL.

​
Remote dashboard is visible but read-only

That is expected when dashboard auth is disabled. Either:
  • keep it read-only for lightweight remote inspection, or
  • run ccs config auth setup on the host to unlock remote changes

​
”Too many login attempts”

Rate limiting triggered. Wait 15 minutes or restart the dashboard.

​
Session expires unexpectedly

Increase session_timeout_hours or check that the session secret is stable between restarts.