# 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/ko/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 토큰에 저장소 읽기 권한이 있는지 확인하세요.