본문으로 건너뛰기

CLI 참조

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

기본 사용법

명령만 실행하면 됩니다. 인수는 필요하지 않습니다:

셸
npx termbridge

이 명령은 로컬 서버, tmux 세션, 기본 Cloudflare 터널 등 모든 항목을 시작합니다.

하위 명령 없이 termbridge을 실행하는 것은 termbridge start을 실행하는 것과 같습니다.

모든 플래그를 지정해 termbridge start을 명시적으로 실행할 수도 있습니다:

셸
termbridge start --port 8080 --proxy 5173 --session dev --kill-on-exit --no-qr --tunnel cloudflare

플래그

플래그 기능 기본값
--port <port> 임의 포트 대신 특정 포트 사용 임의
--proxy <port> 로컬 개발 서버 프록시(Terminal/Preview 뷰 활성화) -
--session <name> tmux 세션 이름 지정 자동 생성
--kill-on-exit Termbridge 종료 시 tmux 세션 정리 끔
--no-qr QR 코드 출력 안 함(스크립트에 유용) 끔
--no-tunnel 터널 비활성화(--public-url 필요) 끔
--public-url <url> 터널 비활성화 시 공개 URL -
--tunnel <provider> 터널 제공자(cloudflare 또는 none) cloudflare
--tunnel-token <token> 이름이 지정된 Cloudflare Tunnel 토큰 사용(--port 필요) -
--tunnel-url <url> 이름이 지정된 터널의 공개 URL(--tunnel-token와 함께 필수) -
--backend <backend> 터미널 백엔드(tmux 또는 sandbox-daytona) tmux
--sandbox-repo <url> Daytona 샌드박스에 복제할 저장소 URL -
--sandbox-branch <branch> 샌드박스에서 체크아웃할 브랜치 -
--sandbox-path <path> 샌드박스 내 저장소 경로 저장소 이름에서 파생
--sandbox-name <name> 샌드박스 이름 임의 termbridge-<hex>
--sandbox-preview-port <port> 샌드박스 내 미리보기 포트 -
--sandbox-public 공개 샌드박스 생성 끔(직접 모드에서는 켜짐)
--sandbox-direct Daytona 샌드박스 안에서 서버 실행(터널 없음) 끔
--dev-proxy-url <url> 개발 스크립트에서 사용하는 localhost:<proxy port> 대신 이 URL로 미리보기 트래픽 프록시 -
-h, --help 도움말 출력 -

다른 옵션은 unknown option: <flag> 오류를 발생시킵니다. --version 플래그는 없습니다.

플래그는 환경 변수보다 우선합니다. 예외는 하나로, 현재 TERMBRIDGE_TUNNEL이 --tunnel 및 --no-tunnel보다 우선합니다(#5).

참고 내장된 termbridge --help 출력에는 여전히 --daytona-* 플래그와 --backend tmux | daytona가 표시됩니다. 이 이름은 거부되므로 위 표의 --sandbox-* 플래그와 --backend sandbox-daytona를 사용하세요(#1).

예시

기존 tmux 세션에 연결

이미 실행 중인 tmux 세션이 있다면:

셸
termbridge --session my-session

고정 포트 및 사용자 지정 세션

셸
termbridge --port 8080 --session codex

깔끔하게 종료(세션 잔여 없음)

셸
termbridge --kill-on-exit

스크립팅(QR 출력 없음)

셸
termbridge --no-qr

Vite 개발 서버 프록시

셸
# Start your Vite app first
cd my-app && npm run dev  # runs on port 5173

# Then start Termbridge with proxy
termbridge --proxy 5173

Views 버튼을 사용해 Terminal과 Preview 사이를 전환하세요. Preview는 HMR을 지원하는 프록시를 통해 앱을 불러옵니다.

이름이 지정된 Cloudflare 터널(토큰 기반)

Cloudflare 계정이 있고 trycloudflare 요청 제한을 피하려면:

셸
termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com

터널 비활성화(자체 공개 URL 사용)

셸
termbridge --no-tunnel --public-url https://example.com

환경 변수

Termbridge은 셸과 실행 디렉터리의 .env 파일에서 환경 변수를 읽습니다. 셸에 이미 설정된 변수는 .env 파일보다 우선합니다.

핵심 설정

변수 기능
TERMBRIDGE_SESSIONS=2 시작 시 여러 tmux 세션 생성
TERMBRIDGE_TMUX_CWD=/path 새 tmux 세션의 작업 디렉터리
TERMBRIDGE_PUBLIC_URL=https://example.com 터널 비활성화 시 공개 URL
TERMBRIDGE_TUNNEL=none 터널 비활성화
TERMBRIDGE_TUNNEL_TOKEN=<token> 이름이 지정된 터널 토큰(TERMBRIDGE_TUNNEL_URL 필요)
TERMBRIDGE_TUNNEL_URL=https://term.example.com 이름이 지정된 터널의 공개 URL

고급 설정

Daytona 직접 모드는 샌드박스 안에서 실행하는 서버에 이 값을 설정합니다. 직접 설정할 수도 있습니다.

변수 기능
TERMBRIDGE_HOST=0.0.0.0 서버가 바인딩하는 주소(기본값 127.0.0.1). 출력되는 로컬 URL에는 항상 127.0.0.1이 표시됩니다.
TERMBRIDGE_COOKIE_SAMESITE=lax 세션 쿠키의 SameSite 값: lax, strict 또는 none(기본값 Lax, 직접 모드에서는 None)
TERMBRIDGE_SHARE_FILE=/path/share-url.txt 공유 URL도 이 파일에 기록
TERMBRIDGE_HIDE_TERMINAL_SWITCHER=1 UI에서 터미널 전환기 숨기기
TERMBRIDGE_TMUX_PATH_PREFIX=/path/bin 각 tmux 세션에서 Termbridge이 시작하거나 연결할 때 PATH 앞에 추가(세션에 export 명령으로 입력)

개발

변수 기능
TERMBRIDGE_INSECURE_COOKIE=1 HTTP 쿠키 허용(로컬 개발 전용)
TERMBRIDGE_PROXY_PORT=5173 dev:beam:proxy 스크립트의 프록시 포트
TERMBRIDGE_DEV_UI=http://127.0.0.1:5000 Vite 개발 UI URL 재정의
TERMBRIDGE_DEV_PORT=3000 개발 중 Termbridge 서버 포트 재정의(기본값 8787)
TERMBRIDGE_DEV_SESSION=codex dev:beam의 tmux 세션 이름(기본값 codex)
TERMBRIDGE_SKIP_BUILD=1 dev:beam에서 CLI 빌드 건너뛰기

샌드박스(Daytona)

변수 기능
TERMBRIDGE_BACKEND=sandbox-daytona Daytona 샌드박스 백엔드 사용
TERMBRIDGE_SANDBOX_DIRECT=true 샌드박스 안에서 Termbridge 실행
TERMBRIDGE_SANDBOX_SERVER_PORT=8080 샌드박스 내 서버 포트
TERMBRIDGE_SANDBOX_AGENTS=claude-code,codex 에이전트용 인증 자동 설치 및 동기화
TERMBRIDGE_SANDBOX_AGENT_ENV=... 전달할 추가 환경 변수
TERMBRIDGE_SANDBOX_AGENT_AUTH_PATHS=... 동기화할 로컬 인증 파일

전체 Daytona 설정은 Daytona 가이드를 참조하세요.

Termbridge 중지

Termbridge이 실행 중인 터미널에서 Ctrl+C을 누르세요. 그러면 다음 작업이 수행됩니다:

  • 터널을 닫습니다(활성화된 경우)
  • 로컬 서버를 중지합니다
  • tmux 세션은 유지합니다(--kill-on-exit을 사용한 경우 제외)

기본적으로 tmux 세션은 유지되므로 나중에 다시 연결할 수 있습니다.