본문으로 건너뛰기

Daytona

Markdown으로 보기 GitHub에서 수정 문서 위치 1675df8

Daytona를 사용하면 클라우드 샌드박스에서 Termbridge 터미널과 미리보기를 실행할 수 있습니다. 재현 가능한 환경이나 클라우드 미리보기가 필요하거나 노트북을 쉬게 하고 싶을 때 사용하세요.

요구 사항

  • Daytona API 키
  • 샌드박스에서 복제할 수 있는 저장소 URL
  • 저장소가 비공개인 경우 Git 인증 정보

빠른 시작

백엔드를 Daytona으로 설정하고 저장소 구성을 지정하세요:

셸
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를 실행하세요:

셸
npx termbridge

항상 TERMBRIDGE_SANDBOX_REPO(또는 --sandbox-repo)을 설정하세요. 설정하지 않으면 Termbridge는 현재 공개적으로 접근할 수 없는 내장 기본 저장소를 사용하므로 샌드박스 생성은 성공하지만 복제에 실패합니다(#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 미리보기 링크입니다.

셸
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 자격 증명을 제공하세요.

셸
export TERMBRIDGE_SANDBOX_GIT_USERNAME=your_github_username
export TERMBRIDGE_SANDBOX_GIT_TOKEN=your_github_token

TERMBRIDGE_SANDBOX_GIT_PASSWORD도 지원되며, 설정하면 토큰보다 우선합니다.

코딩 에이전트

Termbridge는 샌드박스에 코딩 에이전트를 설치하고 로컬 인증 정보를 동기화해 바로 사용할 수 있도록 준비합니다.

전체 설정, 자동 모드 및 보안 세부 정보는 코딩 에이전트 안내서를 참조하세요.

미리보기 모드

미리보기 화면을 표시하려면 TERMBRIDGE_SANDBOX_PREVIEW_PORT을 샌드박스 내 개발 서버가 사용하는 포트로 설정하세요.

Vite의 경우 모든 인터페이스에 바인딩해야 합니다:

셸
npm run dev -- --host 0.0.0.0 --port 5173

Termbridge는 Daytona 미리보기 링크를 가져와 Termbridge 서버를 통해 프록시하므로 미리보기가 UI 안에서 로드됩니다.

공개 샌드박스와 비공개 샌드박스

변수 기능
TERMBRIDGE_SANDBOX_PUBLIC=true 공개 샌드박스를 만듭니다
TERMBRIDGE_SANDBOX_PUBLIC=false 비공개 샌드박스를 만듭니다

변수를 설정하지 않으면 샌드박스는 비공개입니다. 단, 직접 모드에서는 공개됩니다.

비공개 샌드박스에서 Termbridge는 미리보기를 프록시할 때 미리보기 토큰을 자동으로 전달합니다.

정리 및 수명 주기

Termbridge가 종료될 때 샌드박스를 삭제하려면 다음을 설정하세요:

셸
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true

수명이 짧거나 테스트용인 샌드박스에는 접두사를 사용하세요:

셸
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).

문제 해결

미리보기 화면이 비어 있음

  • 샌드박스 내에서 개발 서버가 실행 중인지 확인하세요.
  • 미리보기 포트에 접근할 수 있도록 --host 0.0.0.0을 사용하세요.
  • TERMBRIDGE_SANDBOX_PREVIEW_PORT이 개발 서버 포트와 일치하는지 확인하세요.

할당량 오류로 샌드박스 생성 실패

  • Daytona 대시보드에서 오래된 샌드박스를 삭제하세요.
  • 수명이 짧은 세션에는 TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true을 사용하세요.

저장소 복제 실패

  • 저장소 URL, 브랜치 및 인증 정보를 확인하세요.
  • Git 토큰에 저장소 읽기 권한이 있는지 확인하세요.