​

Headless Workflow

​

Interactive OAuth Modes

​

Paste-Callback Mode (Recommended)

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

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

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

​

Port Forwarding Mode

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

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

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

​

Auto-Detection

• SSH_CONNECTION environment variable
• SSH_CLIENT environment variable
• TTY detection

​

Usage

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

# Codex headless
ccs codex --headless "prompt"

# Claude headless
ccs claude --headless "prompt"

# Kimi headless
ccs kimi --headless "prompt"

​

Pre-Caching Tokens

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