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
| Situation | What users see |
|---|
| Localhost access, auth disabled | Dashboard opens normally without login |
| Remote/IP access, auth disabled | Dashboard UI can open, but sensitive management routes stay localhost-only |
| Remote/IP access, auth enabled but incomplete | Login page shows a setup-state message instead of a misleading blank sign-in form |
| Remote/IP access, auth enabled and configured | Full authenticated dashboard access |
ccs config auth setup.
Quick Setup
Recommended Path
ccs config auth setup
ccs config auth show
ccs config
- 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
config.yaml
Environment Variables
dashboard_auth:
enabled: true
username: admin
password_hash: "$2b$10$your-bcrypt-hash-here"
session_timeout_hours: 24
export CCS_DASHBOARD_AUTH_ENABLED=true
export CCS_DASHBOARD_USERNAME=admin
export CCS_DASHBOARD_PASSWORD_HASH='$2b$10$your-bcrypt-hash-here'
config.yaml.
Login Flow
When authentication is enabled:
- Open the dashboard URL printed by
ccs config
- If auth is configured correctly, CCS redirects you to the login page
- Enter username and password
- On success, CCS returns you to the original destination
- 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
| Key | Type | Default | Description |
|---|
enabled | boolean | false | Enable or disable dashboard login |
username | string | "" | Login username |
password_hash | string | "" | Bcrypt password hash |
session_timeout_hours | number | 24 | Session lifetime in hours |
Environment Variables
| Variable | Maps to |
|---|
CCS_DASHBOARD_AUTH_ENABLED | dashboard_auth.enabled |
CCS_DASHBOARD_USERNAME | dashboard_auth.username |
CCS_DASHBOARD_PASSWORD_HASH | dashboard_auth.password_hash |
CCS_SESSION_SECRET | Custom 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
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.