> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH 访问

<Note>
  如果你只需要一个交互式终端,可以直接使用 CLI 的 `connect` 命令连接到 Sandbox 的 Remote Shell,无需任何 SSH 配置。详见 [Remote Shell](/docs/sandbox/cli-remote-shell)。
</Note>

你可以使用 WebSocket 代理,通过 SSH 连接到你的 Sandbox。

借助 SSH,你可以安全地连接到远程命令行环境,通过 SCP 或 SFTP 等协议传输文件,并使用依赖 SSH 连接的软件。

## 快速开始

### 1. 构建 SSH Template

定义一个 Template,其中包含用于 SSH 访问的 OpenSSH 服务器,以及用于转发基于 WebSocket 连接的 [websocat](https://github.com/vi/websocat)。

<CodeGroup>
  ```python Python theme={null}
  from ppio_sandbox import PPIO, wait_for_port

  ppio = PPIO()

  template = (
      ppio.template.new().from_ubuntu_image("25.04")
      .apt_install(["openssh-server"])
      .run_cmd(
          [
              "curl -fsSL -o /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl",
              "chmod a+x /usr/local/bin/websocat",
          ],
          user="root",
      )
      .set_start_cmd(
          "sudo websocat -b --exit-on-eof ws-l:0.0.0.0:8081 tcp:127.0.0.1:22",
          wait_for_port(8081),
      )
  )

  ppio.template.build(template, "ssh-ready", cpu_count=2, memory_mb=2048)
  ```

  ```typescript JavaScript & TypeScript theme={null}
  import { PPIO, waitForPort } from 'ppio-sandbox'

  const ppio = new PPIO()

  const template = ppio.template.new()
    .fromUbuntuImage('25.04')
    .aptInstall(['openssh-server'])
    .runCmd(
      [
        'curl -fsSL -o /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl',
        'chmod a+x /usr/local/bin/websocat',
      ],
      { user: 'root' }
    )
    .setStartCmd(
      'sudo websocat -b --exit-on-eof ws-l:0.0.0.0:8081 tcp:127.0.0.1:22',
      waitForPort(8081)
    )

  await ppio.template.build(template, 'ssh-ready', {
    cpuCount: 2,
    memoryMB: 2048,
  })
  ```
</CodeGroup>

### 2. 使用该 Template 启动 Sandbox

<CodeGroup>
  ```python Python theme={null}
  from ppio_sandbox import PPIO

  ppio = PPIO()

  sbx = ppio.sandbox.create("ssh-ready")
  print(sbx.sandbox_id)
  ```

  ```typescript JavaScript & TypeScript theme={null}
  import { PPIO } from 'ppio-sandbox'

  const ppio = new PPIO()

  const sbx = await ppio.sandbox.create('ssh-ready')
  console.log(sbx.sandboxId)
  ```
</CodeGroup>

### 3. 从本地机器连接

<Note>
  以下示例以 cn-beijing-1 区域为例，请根据所使用的[区域](/docs/sandbox/overview#区域)替换域名（例如 cn-shanghai-1 区域使用 `sandbox.ppio.cn`）。执行前请将 `<user>` 替换为 Sandbox 内的用户名（默认 Template 为 `user`），`%h` 位置在实际执行时填入 Sandbox ID，即 `ssh ... <user>@<sandbox_id>`。
</Note>

<CodeGroup>
  ```bash macOS theme={null}
  # 安装 websocat
  brew install websocat

  # 连接到你的 Sandbox
  ssh -o 'ProxyCommand=websocat --binary -B 65536 - wss://8081-%h.cn-beijing-1.sandbox.ppio.com' <user>@<sandbox_id>
  ```

  ```bash Linux theme={null}
  # 安装 websocat
  sudo curl -fsSL -o /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl
  sudo chmod a+x /usr/local/bin/websocat

  # 连接到你的 Sandbox
  ssh -o 'ProxyCommand=websocat --binary -B 65536 - wss://8081-%h.cn-beijing-1.sandbox.ppio.com' <user>@<sandbox_id>
  ```
</CodeGroup>

## 工作原理

[Websocat](https://github.com/vi/websocat) 充当代理,SSH 连接通过 Sandbox 暴露的端口以 WebSocket 方式转发。