# Daytona

Daytona 可让 Termbridge 在云沙盒中运行你的终端和预览。适用于需要可复现环境、云端预览或让笔记本电脑保持空闲的场景。

## 要求

- 一个 Daytona API 密钥
- 沙盒可以克隆的仓库 URL
- 如果仓库是私有的，则需要 Git 凭据

## 快速开始

将后端设置为 Daytona，并提供仓库配置：

```bash
export TERMBRIDGE_BACKEND=sandbox-daytona
export TERMBRIDGE_DAYTONA_API_KEY=your_key
export TERMBRIDGE_SANDBOX_REPO=https://github.com/you/your-repo.git
export TERMBRIDGE_SANDBOX_BRANCH=main
export TERMBRIDGE_SANDBOX_PATH=your-repo
export TERMBRIDGE_SANDBOX_NAME=termbridge-sandbox
export TERMBRIDGE_SANDBOX_PUBLIC=true
export TERMBRIDGE_SANDBOX_PREVIEW_PORT=5173
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true
```

然后照常运行 Termbridge：

```bash
npx termbridge
```

始终设置 `TERMBRIDGE_SANDBOX_REPO`（或 `--sandbox-repo`）。如果未设置，Termbridge 当前会回退到内置的默认仓库，而该仓库无法公开访问，因此会创建沙盒，但克隆会失败（[#2](https://github.com/inline0/termbridge/issues/2)）。

## Daytona 连接

| 变量 | 用途 |
| --- | --- |
| `TERMBRIDGE_DAYTONA_API_KEY` | 你的 Daytona API 密钥 |
| `TERMBRIDGE_DAYTONA_API_URL` | API 端点（默认值为 `https://app.daytona.io/api`）|
| `TERMBRIDGE_DAYTONA_TARGET` | Daytona 目标区域（可选）|

这些参数会传递给 Daytona SDK。如果未设置其中某项，SDK 会回退到自己的 `DAYTONA_API_KEY`、`DAYTONA_API_URL` 或 `DAYTONA_TARGET` 变量。

## 直接沙盒模式（无隧道）

直接模式会在沙盒内运行 Termbridge 服务器，并完全跳过 Cloudflare。共享的 URL 是指向沙盒服务器的 Daytona 预览链接。

```bash
export TERMBRIDGE_BACKEND=sandbox-daytona
export TERMBRIDGE_SANDBOX_DIRECT=true
export TERMBRIDGE_SANDBOX_SERVER_PORT=8080
```

`TERMBRIDGE_SANDBOX_SERVER_PORT`（或 `--port`）默认为 `8080`。直接模式会创建一个公开沙盒，除非你设置了 `TERMBRIDGE_SANDBOX_PUBLIC=false`；UI 会隐藏终端切换器。

仍可通过设置 `TERMBRIDGE_SANDBOX_PREVIEW_PORT` 启用预览；在直接模式下，它会作为服务器的 `--proxy` 端口转发。

## 克隆仓库

Termbridge 会创建沙盒，并将你的仓库克隆到沙盒工作目录中。

使用以下设置：

| 变量 | 用途 |
| --- | --- |
| `TERMBRIDGE_SANDBOX_REPO` | 要克隆的仓库 URL（务必设置，参见快速入门）|
| `TERMBRIDGE_SANDBOX_BRANCH` | 要检出的分支（可选）|
| `TERMBRIDGE_SANDBOX_PATH` | 仓库在沙盒中的路径（可选）|
| `TERMBRIDGE_SANDBOX_NAME` | 沙盒名称（可选，默认为 `termbridge-<random hex>`）|

如果未设置 `TERMBRIDGE_SANDBOX_PATH`，Termbridge 会根据仓库名称推导其值。

## 私有代码库

克隆私有仓库时，请提供 git 凭据：

```bash
export TERMBRIDGE_SANDBOX_GIT_USERNAME=your_github_username
export TERMBRIDGE_SANDBOX_GIT_TOKEN=your_github_token
```

也支持 `TERMBRIDGE_SANDBOX_GIT_PASSWORD`；如果设置了它，就会覆盖令牌。

## 编码代理

Termbridge 可以在沙盒内安装编码代理，并同步你的本地身份验证信息，让它们立即就绪。

完整设置说明、自动模式和安全详情，请参阅 [编码代理](https://termbridge.inline0.dev/zh/docs/sandboxes/coding-agents)指南。

## 预览模式

若要显示预览视图，请将 `TERMBRIDGE_SANDBOX_PREVIEW_PORT` 设置为开发服务器在沙盒内使用的端口。

对于 Vite，请确保绑定到所有网络接口：

```bash
npm run dev -- --host 0.0.0.0 --port 5173
```

Termbridge 会获取 Daytona 预览链接，并通过 Termbridge 服务器代理该链接，使预览在 UI 内加载。

## 公开与私有沙盒

| 变量 | 作用 |
| --- | --- |
| `TERMBRIDGE_SANDBOX_PUBLIC=true` | 创建公开沙盒 |
| `TERMBRIDGE_SANDBOX_PUBLIC=false` | 创建私有沙盒 |

未设置此变量时，沙盒默认为私有；但在直接模式下，沙盒为公开。

对于私有沙盒，Termbridge 会在代理预览时自动转发预览令牌。

## 清理与生命周期

若要在 Termbridge 退出时删除沙盒：

```bash
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true
```

对于短期或测试用沙盒，请使用前缀：

```bash
export TERMBRIDGE_SANDBOX_NAME=termbridge-test-$(date +%s)
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true
```

这样可以控制沙盒用量，避免磁盘配额问题。

## CLI 标志

也可以通过标志配置 Daytona。标志的优先级高于对应的环境变量。

| 标志 | 环境变量 | 用途 |
| --- | --- | --- |
| `--backend sandbox-daytona` | `TERMBRIDGE_BACKEND` | 使用 Daytona 后端 |
| `--sandbox-repo <url>` | `TERMBRIDGE_SANDBOX_REPO` | 仓库 URL |
| `--sandbox-branch <branch>` | `TERMBRIDGE_SANDBOX_BRANCH` | 分支 |
| `--sandbox-path <path>` | `TERMBRIDGE_SANDBOX_PATH` | 仓库在沙盒中的路径 |
| `--sandbox-name <name>` | `TERMBRIDGE_SANDBOX_NAME` | 沙盒名称 |
| `--sandbox-preview-port <port>` | `TERMBRIDGE_SANDBOX_PREVIEW_PORT` | 预览端口 |
| `--sandbox-public` | `TERMBRIDGE_SANDBOX_PUBLIC=true` | 创建公开沙盒 |
| `--sandbox-direct` | `TERMBRIDGE_SANDBOX_DIRECT=true` | 在沙盒内运行服务器（无隧道）|

没有用于私有沙盒的标志；请使用 `TERMBRIDGE_SANDBOX_PUBLIC=false`。内置的 `termbridge --help` 输出仍会显示 `--daytona-*` 名称和 `--backend daytona`，但这些会被拒绝（[#1](https://github.com/inline0/termbridge/issues/1)）。

## 故障排除

**预览视图为空白**
- 确保开发服务器正在沙盒内运行。
- 使用 `--host 0.0.0.0`，以便访问预览端口。
- 确认 `TERMBRIDGE_SANDBOX_PREVIEW_PORT` 与开发服务器端口一致。

**创建沙盒时出现配额错误**
- 在 Daytona 控制面板中删除旧沙盒。
- 对于短期会话，请使用 `TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true`。

**克隆仓库失败**
- 仔细检查仓库 URL、分支和凭据。
- 确保 Git 令牌具有仓库读取权限。