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

# Account Safety

> Cross-provider isolation, ban detection, and quota monitoring to protect Google accounts

# Account Safety

Automatic protections to prevent Google account bans when using multiple OAuth providers simultaneously.

## Overview

When the same Google email is authenticated across multiple providers (gemini, agy, codex), simultaneous usage can trigger Google's abuse detection. CCS automatically isolates accounts to prevent this.

<Warning>
  This feature addresses [Issue #509](https://github.com/kaitranntt/ccs/issues/509). If you use the same Google email across gemini and agy, enable cross-provider isolation.
</Warning>

## Cross-Provider Isolation

### How It Works

<Steps>
  <Step title="Detect Duplicates">
    On session launch, CCS scans all providers for emails appearing in 2+ Google OAuth providers
  </Step>

  <Step title="Auto-Pause">
    Conflicting accounts in other providers are temporarily paused
  </Step>

  <Step title="Session Runs">
    Only one provider uses the shared email at a time
  </Step>

  <Step title="Auto-Restore">
    On session exit, paused accounts are restored automatically
  </Step>
</Steps>

**Example:** If `john@gmail.com` is authenticated in both `gemini` and `agy`, starting a `gemini` session auto-pauses the `agy` account for `john@gmail.com`.

### Crash Recovery

If CCS crashes without restoring paused accounts:

* Next launch detects stale sessions (dead PIDs)
* Automatically restores accounts from dead processes
* Persistence file: `~/.ccs/cliproxy/auto-paused.json`

## Ban Detection

CCS monitors for ban-related error patterns during sessions:

**Detected Patterns:**

* `disabled in this account`
* `violation of terms of service`
* `account has been disabled/suspended/banned`

**On Detection:**

1. Affected account is auto-paused immediately
2. No further retries on banned account
3. Warning displayed with box border

## Runtime Quota Monitoring

<Note>
  Available since v7.42.0. Monitors quota during active sessions, not just at startup.
</Note>

### Quota Warning

When quota falls below 20%, CCS displays a warning:

```
╔═══════════════════════════════════════╗
║ [!] Quota below 20% for codex        ║
║     Daily: 48/50 messages remaining   ║
╚═══════════════════════════════════════╝
```

### Quota Exhaustion

When quota is fully exhausted:

1. Applies cooldown period to exhausted account
2. Finds healthy alternative account (if available)
3. Switches default account automatically
4. Logs the switch for transparency

Before local CLIProxy startup, CCS also checks the active provider account pool.
If a non-default account is already quota-exhausted and another healthy account
exists, CCS temporarily pauses the exhausted account so CLIProxy does not keep
routing requests to it. The pause uses the same cooldown metadata as runtime
quota exhaustion and resumes automatically when the cooldown expires.

## Antigravity Responsibility Checklist

<Note>Available since v7.49.0</Note>

When adding a new Antigravity account via the dashboard, a responsibility checklist is displayed. Users must acknowledge guidelines before the account is activated:

* Account usage policies
* Rate limit awareness
* Fair use expectations

This checklist appears in the "Add Account" dialog for the Antigravity provider and helps prevent unintentional policy violations.

## Configuration

Account safety runs automatically with no configuration needed. Behavior is controlled internally based on provider auth files.

### Manual Account Management

```bash theme={null}
# Pause an account manually
ccs cliproxy pause <provider> <account>

# Resume a paused account
ccs cliproxy resume <provider> <account>

# Check status of all accounts
ccs cliproxy status
```

## Token Storage

OAuth tokens are stored locally with restricted permissions:

| Path                               | Permission          | Contents                                            |
| ---------------------------------- | ------------------- | --------------------------------------------------- |
| `~/.ccs/cliproxy/auth/`            | `0o600` (user-only) | Individual OAuth token files per provider account   |
| `~/.ccs/cliproxy/accounts.json`    | `0o600`             | Account registry with pause state and tier metadata |
| `~/.ccs/cliproxy/auto-paused.json` | `0o600`             | Auto-pause session tracking                         |

Tokens are never transmitted outside of the local CLIProxy instance. CLIProxy listens on `127.0.0.1:8317` by default.

## Dashboard Authentication

If you expose the dashboard on a non-loopback address (e.g. `ccs config --host 0.0.0.0`), enable password protection first:

```bash theme={null}
# Set up dashboard authentication
ccs config auth setup
```

This adds HTTP basic auth to the dashboard server. Without it, any device on your network can access your account configuration and OAuth tokens.

<Warning>
  Always run `ccs config auth setup` before using `ccs config --host 0.0.0.0` on a shared or untrusted network.
</Warning>

## Best Practices

* Use separate Google accounts for each OAuth provider (gemini, agy, codex)
* Do not reuse the same email across gemini and agy (see [Issue #509](https://github.com/kaitranntt/ccs/issues/509))
* Enable dashboard auth before exposing the dashboard beyond localhost
* Review the Antigravity responsibility checklist when adding new accounts
* CCS is provided as-is and does not take responsibility for account bans or access loss resulting from usage

## Storage

| Path                               | Purpose                           |
| ---------------------------------- | --------------------------------- |
| `~/.ccs/cliproxy/auto-paused.json` | Auto-pause session tracking       |
| `~/.ccs/cliproxy/accounts.json`    | Account registry with pause state |
| `~/.ccs/cliproxy/auth/`            | OAuth token files per provider    |

## Troubleshooting

### Account Stuck in Paused State

**Symptom:** Account not rotating after crash

**Solution:**

```bash theme={null}
# Check paused accounts
ccs cliproxy status <provider>

# Manually resume
ccs cliproxy resume <provider> <account>
```

### False Ban Detection

**Symptom:** Account paused but not actually banned

**Solution:** Resume manually and monitor:

```bash theme={null}
ccs cliproxy resume <provider> <account>
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-Account Setup" icon="users" href="/tutorials/multi-account-setup">
    Configure multiple accounts per provider
  </Card>

  <Card title="Dashboard" icon="gauge" href="/features/dashboard/overview">
    Monitor account status via web UI
  </Card>
</CardGroup>