> ## 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

> Optional dashboard login with host-setup guidance and remote read-only fallback

# 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.

<Info>
  CCS does not ship a default dashboard username or password.
</Info>

<Note>
  Enable dashboard auth whenever the bind is reachable from another device,
  including when you run `ccs config --host 0.0.0.0`.
</Note>

## 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                                               |

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

### Recommended Path

```bash theme={null}
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

<Tabs>
  <Tab title="config.yaml">
    ```yaml theme={null}
    dashboard_auth:
      enabled: true
      username: admin
      password_hash: "$2b$10$your-bcrypt-hash-here"
      session_timeout_hours: 24
    ```
  </Tab>

  <Tab title="Environment Variables">
    ```bash theme={null}
    export CCS_DASHBOARD_AUTH_ENABLED=true
    export CCS_DASHBOARD_USERNAME=admin
    export CCS_DASHBOARD_PASSWORD_HASH='$2b$10$your-bcrypt-hash-here'
    ```
  </Tab>
</Tabs>

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

| 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

### 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:

```bash theme={null}
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.