Skip to main content

​
Headless Workflow

Use OAuth providers on servers or remote machines without browser access.
Available since v7.37.0 - Enhanced interactive OAuth mode with auto-detection for SSH sessions and paste-callback flow.

​
Interactive OAuth Modes

Auto-detected on SSH sessions - no manual configuration needed.
CCS supports two interactive OAuth modes for headless environments:
Recommended for most headless scenarios.
ccs gemini --headless
# Or force paste-callback mode
ccs gemini --paste-callback

# Output:
# Open this URL on any device to authenticate:
# https://accounts.google.com/...
#
# 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

ccs gemini --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

SSH session detection is automatic - CCS chooses the best mode for you.
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

ccs gemini --headless

# Output:
# Open this URL on any device to authenticate:
# https://accounts.google.com/...
#
# 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

# Gemini headless
ccs gemini --headless "prompt"

# Codex headless
ccs codex --headless "prompt"

# Antigravity headless
ccs agy --headless "prompt"

# Qwen headless
ccs qwen --headless "prompt"

# iFlow headless
ccs iflow --headless "prompt"

​
Pre-Caching Tokens

For automated environments, authenticate locally first:
  1. Run ccs gemini --auth on local machine
  2. Copy ~/.ccs/cliproxy/auth/*.json to remote server
  3. Use without --headless flag