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

# Headless Workflow

> Use CCS on servers without a browser

# Headless Workflow

Use OAuth providers on servers or remote machines without browser access.

<Note>Available since v7.37.0 - Enhanced interactive OAuth mode with auto-detection for SSH sessions and paste-callback flow.</Note>

## Interactive OAuth Modes

<Note>Auto-detected on SSH sessions - no manual configuration needed.</Note>

CCS supports two interactive OAuth modes for headless environments:

### Paste-Callback Mode (Recommended)

<Note>Recommended for most headless scenarios.</Note>

```bash theme={null}
ccs codex --headless
# Or force paste-callback mode
ccs codex --paste-callback

# Output:
# Open this URL on any device to authenticate:
# https://auth.openai.com/authorize?...
#
# After authorizing, paste the callback URL here:
# Waiting for callback URL...
```

**How it works:**

1. CCS generates authentication URL
2. You open URL on any device with a browser
3. Complete OAuth login
4. GitHub/Provider redirects to callback URL
5. Copy callback URL from browser address bar
6. Paste URL back into CCS terminal
7. CCS extracts token and continues

**Benefits:**

* Works over any SSH connection
* No port forwarding required
* No localhost access needed
* Faster than traditional headless mode

### Port Forwarding Mode

```bash theme={null}
ccs codex --headless

# Output:
# OAuth callback server listening on port 8080
# Forward this port to your local machine:
# ssh -L 8080:localhost:8080 user@remote
#
# Then open: http://localhost:8080/auth
```

**How it works:**

1. CCS starts local callback server
2. You forward port via SSH tunnel
3. Complete OAuth in browser on local machine
4. Callback reaches remote CCS via tunnel

**Use when:**

* SSH port forwarding is available
* Multiple users sharing the same server
* Network policies allow port forwarding

## Auto-Detection

<Note>SSH session detection is automatic - CCS chooses the best mode for you.</Note>

CCS automatically detects SSH sessions via:

* `SSH_CONNECTION` environment variable
* `SSH_CLIENT` environment variable
* TTY detection

When SSH is detected, CCS defaults to **paste-callback mode** unless `--headless` explicitly requests traditional flow.

## Usage

```bash theme={null}
ccs codex --headless

# Output:
# Open this URL on any device to authenticate:
# https://auth.openai.com/authorize?...
#
# Waiting for authentication...
```

## How It Works

1. CCS generates an authentication URL
2. You open the URL on any device with a browser
3. Complete OAuth login
4. CCS detects when tokens are cached
5. Session continues

## Use Cases

* SSH sessions on remote servers
* Docker containers
* CI/CD pipelines (with pre-cached tokens)
* Headless Linux environments

## Commands

```bash theme={null}
# Codex headless
ccs codex --headless "prompt"

# Claude headless
ccs claude --headless "prompt"

# Kimi headless
ccs kimi --headless "prompt"
```

## Pre-Caching Tokens

For automated environments, authenticate locally first:

1. Run `ccs codex --auth` on local machine
2. Copy `~/.ccs/cliproxy/auth/*.json` to remote server
3. Use without `--headless` flag