Skip to main content

​
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

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

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

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

​
Environment Variables

​
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:
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.