1  # Connecting OpenCLI via CDP (Remote/Headless Servers)
  2  
  3  If you cannot use the opencli Browser Bridge extension (e.g., in a remote headless server environment without a UI), OpenCLI provides an alternative: connecting directly to Chrome via **CDP (Chrome DevTools Protocol)**.
  4  
  5  Because CDP binds to `localhost` by default for security reasons, accessing it from a remote server requires an additional networking tunnel.
  6  
  7  This guide is broken down into three phases:
  8  1. **Preparation**: Start Chrome with CDP enabled locally.
  9  2. **Network Tunnels**: Expose that CDP port to your remote server using either **SSH Tunnels** or **Reverse Proxies**.
 10  3. **Execution**: Run OpenCLI on your server.
 11  
 12  ---
 13  
 14  ## Phase 1: Preparation (Local Machine)
 15  
 16  First, you need to start a Chrome browser on your local machine with remote debugging enabled.
 17  
 18  **macOS:**
 19  ```bash
 20  /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
 21    --remote-debugging-port=9222 \
 22    --user-data-dir="$HOME/chrome-debug-profile" \
 23    --remote-allow-origins="*"
 24  ```
 25  
 26  **Linux:**
 27  ```bash
 28  google-chrome \
 29    --remote-debugging-port=9222 \
 30    --user-data-dir="$HOME/chrome-debug-profile" \
 31    --remote-allow-origins="*"
 32  ```
 33  
 34  **Windows:**
 35  ```cmd
 36  "C:\Program Files\Google\Chrome\Application\chrome.exe" ^
 37    --remote-debugging-port=9222 ^
 38    --user-data-dir="%USERPROFILE%\chrome-debug-profile" ^
 39    --remote-allow-origins="*"
 40  ```
 41  
 42  > **Note**: The `--remote-allow-origins="*"` flag is often required for modern Chrome versions to accept cross-origin CDP WebSocket connections (e.g. from reverse proxies like ngrok).
 43  
 44  Once this browser instance opens, **log into the target websites you want to use** (e.g., bilibili.com, zhihu.com) so that the session contains the correct cookies.
 45  
 46  ---
 47  
 48  ## Phase 2: Remote Access Methods
 49  
 50  Once CDP is running locally on port `9222`, you must securely expose this port to your remote server. Choose one of the two methods below depending on your network conditions.
 51  
 52  ### Method A: SSH Tunnel (Recommended)
 53  
 54  If your local machine has SSH access to the remote server, this is the most secure and straightforward method.
 55  
 56  Run this command on your **Local Machine** to forward the remote server's port `9222` back to your local port `9222`:
 57  
 58  ```bash
 59  ssh -R 9222:localhost:9222 your-server-user@your-server-ip
 60  ```
 61  
 62  Leave this SSH session running in the background.
 63  
 64  ### Method B: Reverse Proxy (ngrok / frp / socat)
 65  
 66  If you cannot establish a direct SSH connection (e.g., due to NAT or firewalls), you can use an intranet penetration tool like `ngrok`.
 67  
 68  Run this command on your **Local Machine** to expose your local port `9222` to the public internet securely via ngrok:
 69  
 70  ```bash
 71  ngrok http 9222
 72  ```
 73  
 74  This will print a forwarding URL, such as `https://abcdef.ngrok.app`. **Copy this URL**.
 75  
 76  ---
 77  
 78  ## Phase 3: Execution (Remote Server)
 79  
 80  Now switch to your **Remote Server** where OpenCLI is installed. 
 81  
 82  Depending on the network tunnel method you chose in Phase 2, set the `OPENCLI_CDP_ENDPOINT` environment variable and run your commands.
 83  
 84  ### If you used Method A (SSH Tunnel):
 85  
 86  ```bash
 87  export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
 88  opencli doctor                    # Verify connection
 89  opencli bilibili hot --limit 5    # Test a command
 90  ```
 91  
 92  ### If you used Method B (Reverse Proxy like ngrok):
 93  
 94  ```bash
 95  # Use the URL you copied from ngrok earlier
 96  export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
 97  opencli doctor                    # Verify connection
 98  opencli bilibili hot --limit 5    # Test a command
 99  ```
100  
101  > *Tip: If you provide a standard HTTP/HTTPS CDP endpoint, OpenCLI requests the `/json` target list and picks the most likely inspectable app/page target automatically. If multiple app targets exist, you can further narrow selection with `OPENCLI_CDP_TARGET` (for example `antigravity` or `codex`).*
102  
103  If you plan to use this setup frequently, you can persist the environment variable by adding the `export` line to your `~/.bashrc` or `~/.zshrc` on the server.