kterm

도움말

개발자가 아니어도 따라 할 수 있게 적었습니다. 막히면 alulltro@gmail.com으로 화면 사진과 함께 보내 주세요.

1. 컴퓨터에 설치하기

조종하고 싶은 컴퓨터에 kterm 프로그램(kterm-host)을 설치합니다. 휴대폰 앱만으로는 연결할 수 없습니다. 내려받기

Mac

  1. 내려받은 파일을 열고 kterm Host를 응용 프로그램 폴더로 끌어다 놓습니다.
  2. 응용 프로그램 폴더에서 kterm Host를 엽니다.
  3. 처음 열 때 "인터넷에서 다운로드한 앱입니다. 열겠습니까?"라는 창이 뜹니다. 정상입니다. 열기를 누르세요. kterm은 Apple의 공증(notarization)을 받아 배포합니다.
  4. 그래도 "열 수 없습니다"라고 나오면: 시스템 설정 > 개인정보 보호 및 보안으로 가서 아래쪽의 "kterm이(가) 차단되었습니다" 옆 그래도 열기를 누릅니다.
  5. "kterm이(가) 들어오는 네트워크 연결을 허용하겠습니까?"가 뜨면 허용을 누릅니다. 같은 와이파이에서 휴대폰이 직접 연결할 때 필요합니다.
  6. kterm을 열면 브라우저에 kterm 설정 화면이 뜹니다. 화면 위 메뉴 막대에도 kterm 아이콘이 생깁니다(노치에 가려 안 보일 수 있어요 — 그럴 땐 응용 프로그램에서 kterm을 다시 열면 설정 화면이 뜹니다).
  7. 꼭 한 번: 전체 디스크 접근 권한 켜기. 시스템 설정 > 개인정보 보호 및 보안 > 전체 디스크 접근 권한에서 +를 눌러 kterm Host를 추가하고 켭니다. 설정 화면 위의 안내 배너에 있는 설정 열기 버튼으로 바로 갈 수 있어요.
    왜 필요한가요? 터미널에서 문서·데스크톱·iCloud Drive 폴더를 열면 macOS가 "kterm이 접근하려 합니다"라고 묻습니다. 밖에서 쓰는 중이면 그 창을 누를 사람이 없어서 세션이 멈춥니다. 미리 한 번 켜 두면 묻지 않습니다.

Windows

  1. 내려받은 설치 파일을 실행합니다.
  2. 파란 창으로 "Windows의 PC 보호"가 뜰 수 있습니다. 새로 나온 프로그램이라 Microsoft가 아직 내려받은 사람 수를 충분히 모으지 못해서 뜨는 경고입니다. 창 안의 추가 정보를 누른 다음, 나타나는 실행 버튼을 누르세요.
  3. "Windows 보안 경고 — 일부 기능을 차단했습니다" 창이 뜨면 개인 네트워크에 체크하고 액세스 허용을 누릅니다. 공용 네트워크(카페 와이파이 등)는 체크하지 않아도 됩니다.
  4. 작업 표시줄 오른쪽 아래 알림 영역(^ 모양을 누르면 보이는 곳)에 kterm 아이콘이 생기면 끝입니다.

Linux

  1. 내려받은 파일을 풀고 kterm-host를 실행합니다.
  2. 터미널에 QR이 표시되고, 브라우저로 여는 로컬 설정 화면 주소가 함께 나옵니다.

2. 휴대폰과 연결하기 (QR — 처음 한 번만)

  1. 컴퓨터의 kterm 설정 화면 휴대폰 연결 탭에 QR이 나타납니다.
  2. 휴대폰에서 kterm 앱을 열고 컴퓨터 추가를 누른 뒤 QR을 비춥니다. 카메라 권한을 물으면 허용하세요. QR을 읽는 데만 씁니다.
  3. 휴대폰에 확인 코드 6자리가 뜨고, 컴퓨터에도 같은 숫자와 함께 "연결할까요?"가 뜹니다. 숫자가 같으면 컴퓨터에서 연결을 누르세요.
  4. 컴퓨터 이름이 앱 목록에 나타나면 끝입니다. 이 휴대폰은 다시 QR을 찍을 필요가 없습니다 — 컴퓨터를 껐다 켜도, 앱을 다시 열어도 자동으로 연결됩니다.

컴퓨터 앞에 없을 때 다른 기기 추가하기 (예: 밖에서 아이패드)

  1. 이미 연결한 휴대폰에서 컴퓨터 메뉴 > 다른 기기 추가 (컴퓨터 없이)를 누르면 초대 QR이 나옵니다(10분, 한 번만).
  2. 아이패드의 kterm 앱으로 그 QR을 찍으면 아이패드에 숫자 6자리가 뜹니다.
  3. 휴대폰에 "새 기기가 연결하려고 해요" 창이 뜹니다. 아이패드에 보이는 숫자를 휴대폰에 입력하고 승인하면 끝입니다. 휴대폰이 꺼져 있었다면 알림으로 옵니다.

숫자를 직접 입력하게 한 건 일부러입니다. 버튼 한 번으로 승인되면, 요청을 계속 보내 실수로 누르게 만드는 공격에 약해집니다. 새 기기가 연결되면 다른 기기들에 "새 기기가 연결됐어요" 알림이 가므로 모르는 기기가 생기면 바로 알 수 있습니다.

3. 집 밖에서 연결하기

따로 설정할 것이 없습니다. 앱은 먼저 같은 와이파이에서 컴퓨터를 직접 찾고, 1.5초 안에 못 찾으면 중계 서버를 거쳐 연결합니다. 공유기 포트 열기, VPN, Tailscale 모두 필요 없습니다.

4. Claude Code 알림 연결 Pro

Claude Code가 "계속할까요?" 같은 질문을 남기고 멈추면 휴대폰으로 알림을 받을 수 있습니다.

  1. 휴대폰 앱에서 알림을 허용합니다. (설정 > 알림)
  2. 컴퓨터의 kterm 아이콘 > 설정 > 에이전트 알림에서 Claude Code 연결을 누릅니다. kterm이 Claude Code 설정 파일(~/.claude/settings.json)에 알림 훅을 추가합니다. 기존 설정은 지우지 않습니다.
  3. 이미 열려 있던 Claude Code는 한 번 종료했다가 kterm 세션 안에서 다시 실행합니다.
  4. 세션 목록에 입력 대기 배지가 보이고 알림이 오면 성공입니다. 알림을 누르면 그 세션이 바로 열립니다.

알림에는 "세션이 입력을 기다려요"라는 고정 문구만 표시됩니다. 질문 내용은 앱을 열었을 때 암호화된 연결로만 보입니다. Codex CLI도 같은 메뉴에서 연결합니다.

5. 문제 해결

컴퓨터가 "오프라인"으로 나와요

  1. 컴퓨터가 잠자기 상태인지 확인하세요. 잠든 컴퓨터에는 연결할 수 없고, kterm은 컴퓨터를 깨우지 않습니다. (아래 "잠자기" 항목)
  2. 컴퓨터에 kterm 아이콘이 있는지 확인하세요. 없으면 kterm을 다시 실행합니다. 설정에서 로그인 시 자동 실행을 켜 두면 재부팅 뒤에도 자동으로 켜집니다.
  3. 컴퓨터가 인터넷에 연결되어 있는지 확인하세요.
  4. 앱에 "이 기기는 연결이 해제되었습니다"가 나오면 컴퓨터 쪽에서 기기를 해제한 것입니다. 새 QR로 다시 연결하세요.
  5. 그래도 안 되면 컴퓨터의 kterm을 종료했다가 다시 실행합니다.

세션을 열었는데 프롬프트가 안 뜨고 멈춰 있어요

Mac이라면 거의 항상 macOS 권한 창이 컴퓨터 화면에서 대답을 기다리는 중입니다(문서·iCloud Drive 폴더 접근 등). 앱에도 "셸이 시작하다 멈췄어요" 안내가 뜹니다. 위 설치 단계의 전체 디스크 접근 권한을 켜 두면 생기지 않습니다.

컴퓨터가 잠자기에 들어가요

화면이 꺼지는 것은 괜찮습니다. 컴퓨터 전체가 잠드는 것만 막으면 됩니다.

같은 와이파이인데 느리거나 중계로만 연결돼요

한글이 이상하게 입력돼요

kterm은 화면 아래 입력칸에서 글자를 완성한 뒤 보냅니다. 키보드 단축키 모드(터미널에 키를 바로 보내는 모드)에서는 한글 조합이 되지 않으니 입력칸 모드로 바꿔 주세요. 그래도 깨지면 사용 중인 프로그램 이름과 함께 알려 주세요.

세션을 더 열 수 없다고 나와요

무료 요금제는 컴퓨터마다 동시에 세션 1개를 씁니다. 다른 세션을 종료하거나 Pro로 바꾸면 제한이 없어집니다.

6. 구독·해지·복원

문의

alulltro@gmail.com — 사용하는 휴대폰 기종, 컴퓨터 운영체제, 화면 사진을 함께 보내 주시면 빨리 답할 수 있습니다. 터미널 내용에 비밀번호나 키가 보이면 가리고 보내 주세요.

English: kterm support is Korean-first. Email alulltro@gmail.com in English any time.