Merge pull request #134 from Phala-Network/docs/update-ssh-documentation

docs: update SSH documentation with phala ssh command

Author: h4x3rotab

docs.json

@@ -374,7 +374,8 @@
                       "/phala-cloud/references/phala-cloud-cli/phala/auth",
                       "/phala-cloud/references/phala-cloud-cli/phala/cvms",
                       "/phala-cloud/references/phala-cloud-cli/phala/docker",
-                      "/phala-cloud/references/phala-cloud-cli/phala/simulator"
+                      "/phala-cloud/references/phala-cloud-cli/phala/simulator",
+                      "/phala-cloud/references/phala-cloud-cli/phala/ssh"
                     ]
                   },
                   "/phala-cloud/references/migration-from-dstack-v03"

phala-cloud/getting-started/start-from-cloud-ui.mdx

@@ -42,7 +42,7 @@ Click the **Deploy** -> **docker-compose.yml** in the top-right corner of the cl
         command: "start-notebook.sh --NotebookApp.token=${TOKEN}"
     ```
 
-3.  Choose the **Computing Resources** plan. There are some preset plans available, or you can customize them for more flexibility. In **Node & Image** section, we recommend choosing **dstack-dev-** as guest image if you are deploying for testing. It will enable the debug feature that you can login to the virtual machine in the future.
+3.  Choose the **Computing Resources** plan. There are some preset plans available, or you can customize them for more flexibility. In **Node & Image** section, we recommend choosing **dstack-dev-** as guest image if you are deploying for testing. This enables [SSH access](/phala-cloud/networking/enable-ssh-access) for debugging.
 
 
     <Frame caption="Compute Resources">

phala-cloud/networking/enable-ssh-access.mdx

@@ -1,35 +1,67 @@
 ---
-title: Enable SSH Access  
+title: Enable SSH Access
 description: Connect to your CVM via SSH for debugging and management
 ---
 
 <Warning>
-SSH access is only available when you deploy with a **dev** OS image. Select "dstack-dev" as the OS type when creating your CVM. Production OS images have SSH disabled for security.
+SSH access is only available with **dev** OS images. Select "dstack-dev" when creating your CVM. Production images have SSH disabled for security.
 </Warning>
 
-This guide shows you how to SSH into your CVM through the secure gateway tunnel.
+The easiest way to SSH into your CVM is with the Phala CLI. One command connects you through the secure gateway tunnel.
 
 ## Prerequisites
 
-- SSH client on your local machine
-- OpenSSL installed
+- [Phala CLI](/phala-cloud/phala-cloud-cli/overview) (latest version)
 - CVM deployed with Development OS
 
-## Step 1: Set Root Credentials
+## Step 1: Configure SSH Keys
 
-When deploying your CVM, set one of these environment variables:
+Start by adding your SSH keys in **Account Settings > SSH Keys** on the [Phala Cloud dashboard](https://cloud.phala.com/account/settings). You can add keys manually or sync them from GitHub. All saved keys are automatically added to every new CVM you deploy.
 
-**For password authentication:**
-- Add `DSTACK_ROOT_PASSWORD` as a secure environment variable
+When creating a CVM, the SSH Authorization section lets you add an additional root password or public key specific to that instance. These are added alongside your account keys.
 
-**For key-based authentication (recommended):**
-- Add `DSTACK_ROOT_PUBLIC_KEY` with your SSH public key
+<Note>
+SSH keys are injected **only at CVM creation time**. Updating your account keys won't affect already-deployed CVMs. To modify credentials on existing CVMs, use **Code Update** to set the `DSTACK_ROOT_PASSWORD` or `DSTACK_ROOT_PUBLIC_KEY` environment variables.
+</Note>
+
+## Step 2: Connect
+
+```bash
+# Connect using phala.toml configuration
+phala ssh
+
+# Or specify the CVM name directly
+phala ssh my-cvm
+```
+
+That's it. The CLI handles the gateway tunnel and SSH configuration automatically.
+
+## Useful Options
+
+The `phala ssh` command supports several options:
+
+```bash
+# Preview the SSH command without connecting
+phala ssh my-cvm --dry-run
+
+# Enable verbose output for debugging
+phala ssh my-cvm -v
+
+# Forward a local port to the CVM
+phala ssh my-cvm -- -L 8080:localhost:80
+```
 
-If you need to add credentials after deployment, use "Code Update" in the dashboard to modify environment variables.
+See the [CLI reference](/phala-cloud/references/phala-cloud-cli/phala/ssh) for all options.
 
-## Step 2: Configure Your SSH Client
+<Accordion title="Manual SSH Configuration">
 
-Add this to your `~/.ssh/config` file:
+If you prefer manual configuration or need to customize your setup, use `phala ssh --dry-run` to generate the SSH config:
+
+```bash
+phala ssh my-cvm --dry-run
+```
+
+This outputs a working SSH command you can adapt. The underlying mechanism uses OpenSSL to tunnel SSH through TLS:
 
 ```bash
 Host my-cvm
@@ -39,21 +71,13 @@ Host my-cvm
     ProxyCommand openssl s_client -quiet -connect %h:%p
 ```
 
-Replace:
-- `<app-id>` with your application ID (find it in the dashboard)
-- `<cluster>` with your cluster (e.g., `us`)
-
-## Step 3: Connect
+Replace `<app-id>` with your application ID and `<cluster>` with your cluster (e.g., `dstack-pha-prod7`).
 
-```bash
-ssh my-cvm
-```
+**macOS users:** If you encounter connection timeouts, you may have LibreSSL instead of OpenSSL. Install OpenSSL via Homebrew and use the full path: `/opt/homebrew/bin/openssl`.
 
-That's it. You're now connected to your CVM through the secure gateway tunnel.
+**Windows users:** Install OpenSSL via [Chocolatey](https://chocolatey.org/) (`choco install openssl`) and use the full path in ProxyCommand. Alternatively, use WSL where the Linux instructions work directly.
 
-<Note>
-**macOS users:** If you encounter connection timeouts, you may have LibreSSL instead of OpenSSL. Install OpenSSL via Homebrew (`brew install openssl`) and update your ProxyCommand to use the full path to the Homebrew OpenSSL binary.
-</Note>
+</Accordion>
 
 ## What You Can Do
 
@@ -71,82 +95,18 @@ docker stats
 # Debug networking
 curl http://localhost:8080
 netstat -tulpn
-wg show
 ```
 
-## Security Notes
-
-- SSH traffic is tunneled through TLS via the gateway
-- Only your code inside the TEE can see the decrypted SSH session
-- Use key-based authentication for production debugging
-- Remember to switch to Production OS when you're done debugging
-
-## Windows SSH Access
-
-Windows users can connect to CVMs using PowerShell or Windows Terminal with OpenSSL.
-
-### Option 1: Using Windows OpenSSL
-
-1. **Install OpenSSL for Windows:**
-   - Download from [slproweb.com/products/Win32OpenSSL.html](https://slproweb.com/products/Win32OpenSSL.html)
-   - Or install via Chocolatey: `choco install openssl`
-
-2. **Create SSH config file:**
-
-   Create or edit `C:\Users\<YourUsername>\.ssh\config`:
-   ```
-   Host my-cvm
-       HostName <app-id>-22.<cluster>.phala.network
-       User root
-       Port 443
-       ProxyCommand "C:\Program Files\OpenSSL-Win64\bin\openssl.exe" s_client -quiet -connect %h:%p
-   ```
-
-3. **Connect:**
-   ```powershell
-   ssh my-cvm
-   ```
-
-### Option 2: Using WSL (Windows Subsystem for Linux)
-
-If you have WSL installed, the Linux instructions work directly:
-
-1. Open WSL terminal
-2. Edit `~/.ssh/config` as shown in the main guide
-3. Connect with `ssh my-cvm`
-
-### Option 3: Using PuTTY with Plink
-
-1. Install [PuTTY](https://www.putty.org/)
-2. Use Plink with OpenSSL tunneling:
-   ```powershell
-   plink -proxycmd "openssl s_client -quiet -connect <app-id>-22.<cluster>.phala.network:443" root@<app-id>-22.<cluster>.phala.network
-   ```
-
-<Note>
-**Windows OpenSSL Path:** If you installed OpenSSL to a different location, update the path in the ProxyCommand accordingly.
-</Note>
+<Tip>
+Remember to switch to a Production OS image when you're done debugging.
+</Tip>
 
 ## Troubleshooting
 
-**Permission denied?**
-- Verify your credentials are set in environment variables
-- Use "Code Update" to add them if forgotten during deployment
-
-**Connection timeout?**
-- Check your OpenSSL version: `openssl version`
-- macOS users: ensure you're using OpenSSL, not LibreSSL
-- Windows users: verify OpenSSL is in your PATH or use the full path
-
-**Connection refused?**
-- Confirm you deployed with Development OS, not Production OS
-
-**Windows: 'openssl' is not recognized**
-- Install OpenSSL and add it to your system PATH
-- Or use the full path to openssl.exe in the ProxyCommand
-
-## Next Steps
+| Issue | Solution |
+|-------|----------|
+| Permission denied | Check Account Settings for saved keys. For existing CVMs, use Code Update to set credentials. |
+| Connection refused | Confirm you deployed with Development OS, not Production |
+| Connection timeout | Run `phala ssh -v` to see detailed connection info |
 
-- [Monitor logs](/phala-cloud/monitoring/public-logs)
-- [Set up custom domains](/phala-cloud/networking/setup-custom-domain)
-- [Learn about security](/phala-cloud/networking/security)
+For more detailed troubleshooting, see [Networking Troubleshooting](/phala-cloud/networking/troubleshooting#ssh-access-denied).

phala-cloud/networking/troubleshooting.mdx

@@ -211,32 +211,34 @@ grpcurl -plaintext localhost:50051 list
 
 SSH only works with development OS images. Production images have SSH disabled.
 
-### Check Configuration
+### Debug with Verbose Mode
+
+Use the Phala CLI with verbose output to diagnose connection issues:
 
 ```bash
-# Verify environment variables are set
-DSTACK_ROOT_PASSWORD=yourpassword
-# OR
-DSTACK_ROOT_PUBLIC_KEY=ssh-rsa AAAA...
+phala ssh my-cvm -v
+```
 
-# Test connection
-ssh -v my-cvm
+This shows detailed connection information including gateway resolution and SSH handshake.
 
-# Test ProxyCommand directly
-openssl s_client -connect <app-id>-22.dstack-prod5.phala.network:443
-```
+### Check SSH Keys
+
+SSH keys from Account Settings are only injected at CVM creation time. If you added keys after deployment, use Code Update to set `DSTACK_ROOT_PUBLIC_KEY`.
 
 ### macOS OpenSSL Issue
 
-macOS uses LibreSSL which may cause issues:
+If using manual SSH configuration, macOS LibreSSL may cause timeouts:
+
 ```bash
 # Install OpenSSL via Homebrew
 brew install openssl
 
-# Update SSH config
-ProxyCommand /opt/homebrew/bin/openssl s_client -quiet -connect %h:%p
+# Use full path in ProxyCommand
+/opt/homebrew/bin/openssl s_client -quiet -connect %h:%p
 ```
 
+For detailed SSH setup, see [Enable SSH Access](/phala-cloud/networking/enable-ssh-access).
+
 ## Debugging Commands
 
 ### From Outside CVM

phala-cloud/references/phala-cloud-cli/phala/ssh.mdx

@@ -0,0 +1,126 @@
+---
+description: Connect to a CVM via SSH through the secure gateway tunnel.
+title: ssh
+---
+
+## Command: `ssh`
+
+#### Syntax
+
+```
+phala ssh [options] [<cvm-name>] [--] [...]
+```
+
+### Description
+
+The `phala ssh` command connects you to a CVM via SSH through the secure gateway tunnel. It handles all the gateway configuration automatically.
+
+```bash
+Usage: phala ssh [options] [<cvm-name>] [--] [...]
+
+Connect to a CVM via SSH
+
+Arguments:
+  <cvm-name>?       CVM name. If not provided, reads from phala.toml
+
+Options:
+  -h, --help              Show help information
+  -p, --port <value>      Gateway port (default: 443)
+  -g, --gateway <value>   Gateway domain (skips API call for offline usage)
+  -t, --timeout <value>   Connection timeout in seconds (default: 30)
+  -v, --verbose           Show verbose connection details
+  --dry-run               Print the SSH command without executing it
+
+Pass-through (after --):
+  All arguments after -- are passed directly to ssh.
+```
+
+### Examples
+
+* Connect using phala.toml configuration
+
+```bash
+phala ssh
+```
+
+* Connect to a specific CVM
+
+```bash
+phala ssh my-app
+```
+
+* Preview the SSH command without connecting
+
+```bash
+phala ssh my-app --dry-run
+```
+
+<details>
+
+<summary>Example Output</summary>
+
+```bash
+ssh -o ProxyCommand="openssl s_client -quiet -connect %h:%p" \
+    -o StrictHostKeyChecking=no \
+    root@abc123def456-22.dstack-prod5.phala.network -p 443
+```
+
+</details>
+
+* Connect with verbose output for debugging
+
+```bash
+phala ssh my-app -v
+```
+
+* Forward a local port to the CVM
+
+```bash
+phala ssh my-app -- -L 8080:localhost:80
+```
+
+This forwards your local port 8080 to port 80 on the CVM.
+
+* Set up a SOCKS proxy
+
+```bash
+phala ssh my-app -- -D 1080 -N
+```
+
+This creates a SOCKS proxy on local port 1080 without executing a remote command.
+
+* Execute a remote command
+
+```bash
+phala ssh my-app -- docker ps -a
+```
+
+* Connect with a custom SSH key
+
+```bash
+phala ssh my-app -- -i ~/.ssh/custom_key
+```
+
+* Offline mode (skip API lookup)
+
+```bash
+phala ssh my-app -g dstack-prod5.phala.network -p 443
+```
+
+When you specify the gateway domain, the CLI skips the API call and connects directly.
+
+### Pass-through Options
+
+Any arguments after `--` are passed directly to the underlying SSH command. Common options include:
+
+| Option | Description |
+|--------|-------------|
+| `-i <keyfile>` | Use a specific identity file |
+| `-L <local>:<remote>` | Local port forwarding |
+| `-R <remote>:<local>` | Remote port forwarding |
+| `-D <port>` | Dynamic SOCKS proxy |
+| `-v` | SSH verbose mode |
+
+<Note>
+The `-o ProxyCommand` option is blocked since the CLI manages the proxy configuration automatically.
+</Note>