ccs/docs/dashboard-auth-cli.md

Dashboard Authentication CLI

Last Updated: 2026-03-23

CLI commands for managing CCS dashboard authentication.

Overview

The CCS dashboard (ccs config) can be protected with username/password authentication. This is useful whenever the dashboard is reachable from another device, including when the runtime's default bind is network-accessible or when you explicitly bind it beyond loopback with ccs config --host 0.0.0.0.

Authentication is disabled by default for backward compatibility. Use the CLI to configure and enable it.

When auth stays disabled, CCS now applies a localhost-only fallback on sensitive management endpoints. Remote devices can still open the dashboard UI when you intentionally bind it beyond loopback, but write-capable routes such as AI Provider management and CLIProxy auth/status helpers reject non-loopback requests until you enable dashboard auth.

Account Context Modes (Related Feature)

Dashboard auth and account context metadata are separate:

• dashboard_auth: protects dashboard access with username/password
• accounts.<name>.context_mode/context_group: controls isolated vs shared account context

Account context is isolation-first:

Mode	Default	Requirement
isolated	Yes	No context_group required
shared	No (opt-in)	Valid non-empty context_group

Shared continuity depth:

• standard (default): shares project workspace context only
• deeper (advanced opt-in): also syncs session-env, file-history, shell-snapshots, todos

context_group normalization and validation:

• trim + lowercase + collapse internal whitespace to -
• allowed characters: lowercase letters, numbers, _, -
• must start with a letter
• max length: 64
• shared mode requires non-empty value after normalization
• continuity_mode is only valid when mode is shared

PUT /api/config behavior for account context:

• rejects invalid unified payloads
• rejects explicit context_mode: shared with invalid/empty context_group
• rejects invalid continuity_mode values
• normalizes valid shared context_group before save
• defaults missing shared continuity_mode to standard
• rejects context_group when mode is not shared
• rejects continuity_mode when mode is not shared

Dashboard accounts context editing:

• PUT /api/accounts/:name/context updates context mode/group/continuity for existing auth accounts
• rejects CLIProxy OAuth account keys for this route
• applies normalization/validation rules above

Commands

ccs config auth setup

Interactive wizard to configure dashboard login.

$ ccs config auth setup

╭─────────────────────────────────╮
│  Dashboard Auth Setup           │
╰─────────────────────────────────╯

[i] Configure username and password for dashboard access.
    Password will be hashed with bcrypt before storage.

Username
Enter username: admin

Password
    Minimum 8 characters
Enter password: ********
Confirm password: ********

[i] Hashing password...

[OK] Dashboard authentication configured

[i] Settings saved to ~/.ccs/config.yaml
[i] Username: admin
[i] Session timeout: 24 hours

    Start dashboard: ccs config
    Show status: ccs config auth show
    Disable auth: ccs config auth disable

ccs config auth show

Display current authentication status.

$ ccs config auth show

╭─────────────────────────────────╮
│  Dashboard Auth Status          │
╰─────────────────────────────────╯

Configuration
[OK] Authentication: Enabled
[OK] Username: admin
[i] Session timeout: 24 hours

Commands
  ccs config auth setup     Configure authentication
  ccs config auth disable   Disable authentication
  ccs config                Open dashboard

ccs config auth disable

Disable dashboard authentication with confirmation.

$ ccs config auth disable

╭─────────────────────────────────╮
│  Disable Dashboard Auth         │
╰─────────────────────────────────╯

[!] This will disable login protection for the dashboard.
[i] Anyone with network access will be able to view the dashboard.

Disable authentication? [y/N]: y

[OK] Dashboard authentication disabled

[i] Credentials preserved - re-enable with: ccs config auth setup

ccs config auth --help

Display usage information.

Environment Variables

Environment variables override config.yaml values:

Variable	Description
CCS_DASHBOARD_AUTH_ENABLED	Enable/disable auth (true/false)
CCS_DASHBOARD_USERNAME	Username
CCS_DASHBOARD_PASSWORD_HASH	Bcrypt password hash

Generating a Password Hash

Use bcrypt to generate a hash:

# Using Node.js
node -e "console.log(require('bcrypt').hashSync('your-password', 10))"

# Using npx
npx bcrypt-cli hash "your-password"

Configuration

Settings are stored in ~/.ccs/config.yaml:

# Dashboard Auth: Optional login protection for CCS dashboard
# Generate password hash: npx bcrypt-cli hash "your-password"
# ENV override: CCS_DASHBOARD_AUTH_ENABLED, CCS_DASHBOARD_USERNAME, CCS_DASHBOARD_PASSWORD_HASH
dashboard_auth:
  enabled: true
  username: "admin"
  password_hash: "$2b$10$..."
  session_timeout_hours: 24

Security Notes

1. Bcrypt hashing: Passwords are hashed with bcrypt (10 rounds) before storage
2. Session cookies: Sessions use HTTP-only cookies (not accessible via JavaScript)
3. Rate limiting: Login attempts are rate-limited (5 per 15 minutes)
4. Fail-closed remote writes: When auth is disabled, sensitive management routes allow localhost only
5. File permissions: Config file is created with 0o600 permissions

Troubleshooting

"Authentication not configured"

Run ccs config auth setup to configure credentials.

Forgot password

Run ccs config auth setup again to set a new password.

ENV override not working

Ensure the variable is exported:

export CCS_DASHBOARD_AUTH_ENABLED=true
export CCS_DASHBOARD_USERNAME=admin
export CCS_DASHBOARD_PASSWORD_HASH='$2b$10$...'

Session expired immediately

Check session_timeout_hours in config. Default is 24 hours.

"Invalid ... context_group ..."

This error comes from PUT /api/config when an account explicitly sets shared mode with an invalid group. Use a canonical group value (for example: team-alpha).

See Also

• Dashboard Auth Feature - Full documentation
• Config Schema - All config options