Foreman 사용 가이드

01시작하기

Foreman은 두 부분으로 나뉩니다. 에이전트가 실제로 도는 컴퓨터에는 호스트를, 세션을 보고 승인할 기기에는 앱을 설치합니다. 호스트는 세션을 직접 소유하므로 터미널 창을 닫거나 연결이 끊겨도 에이전트는 계속 돌고, 앱은 언제든 다시 붙습니다.

Mac 호스트 설치

1. Foreman Host 1.0.1 DMG를 내려받아 열고 Foreman Host를 응용 프로그램 폴더로 끌어다 놓습니다. macOS 15 이상, Apple 실리콘과 Intel Mac 모두 됩니다.
2. 응용 프로그램 폴더에서 Foreman Host를 엽니다. Dock에는 나타나지 않고 메뉴 막대에 펄스 아이콘이 생깁니다.
3. 메뉴를 열어 맨 위에 “이 Mac이 호스트로 동작 중”이 보이면 준비가 끝난 것입니다. 그 아래 줄에 foremand 버전, 세션 수, 원격 연결 상태가 나옵니다.
4. 메뉴의 로그인 시 시작을 켭니다. 이제 Mac에 로그인할 때마다 호스트가 자동으로 뜨고, 꺼지면 몇 초 안에 다시 뜹니다. 토글 옆에 “승인 필요”가 보이면 시스템 설정 › 일반 › 로그인 항목에서 Foreman Host를 허용합니다.
5. 같은 Mac에서 Foreman 앱을 쓰면 페어링 없이 바로 이 호스트에 연결됩니다.

Foreman 열기 ⌘O

Foreman 앱을 엽니다.

다른 기기와 페어링…

휴대폰이나 다른 기기를 연결할 QR 코드를 띄웁니다(페어링).

기기 관리…

이 호스트에 페어링된 기기를 보고 폐기합니다.

iCloud·Google 연결…

호스트를 내 클라우드 계정에 연결합니다(클라우드 연결).

잠자기 방지 (세션 실행 중)

세션이 도는 동안 Mac이 잠들지 않게 합니다(항상 켜 두기).

상시 가동 점검…

이 Mac이 아무도 없을 때도 세션을 계속 돌릴 수 있는지 점검하고 고칩니다(Mac 상시 가동 점검).

종료 ⌘Q

Foreman Host 앱만 끝냅니다. 호스트 데몬과 세션은 계속 돕니다.

Windows 호스트 설치

1. Foreman Host 패키지(MSIX)를 설치합니다. Windows 10 버전 1809 이상이 필요합니다.
2. 설치하면 foreman 명령, 호스트 데몬, 개인·도메인 네트워크용 방화벽 규칙이 함께 들어옵니다. 따로 설정할 것은 없습니다.
3. 로그온할 때 호스트가 자동으로 시작되도록 시작 작업 “Foreman Host”가 등록됩니다. PowerShell에서 foreman autostart status로 상태를 확인합니다. 꺼져 있다고 나오면 작업 관리자 › 시작 앱에서 Foreman Host를 켭니다.
4. foreman doctor를 실행해 이 PC가 계속 켜져 있을 준비가 됐는지 확인합니다(항상 켜 두기).

패키지 없이 압축 파일로 받은 호스트는 foreman autostart enable 한 번으로 로그온 시 시작을 켭니다. 관리자 권한은 필요 없습니다.

iPhone · iPad · Mac 앱

iPhone과 iPad는 App Store에서 Foreman을 받습니다. Apple Watch 앱은 iPhone 앱과 함께 설치됩니다. Mac에서 세션을 보려면 Foreman 앱(DMG 내려받기)을, 그 Mac을 호스트로 쓰려면 Foreman Host(DMG 내려받기)를 설치합니다. 두 앱 모두 새 버전이 나오면 앱 안에서 알려 줍니다. 둘은 별개의 앱이고 한 Mac에 같이 둘 수 있습니다.

Android 앱

Google Play에서 Foreman을 받습니다. Android 8.0 이상에서 동작합니다. 아래쪽 탭은 현황, 승인, 세션, 호스트이고, 설정은 현황 오른쪽 위의 계정 아이콘이나 호스트 탭의 톱니바퀴에서 엽니다. 태블릿처럼 화면이 넓으면 탭이 옆으로 옮겨 가고 목록과 상세가 나란히 보입니다.

• 처음 열면 알림 권한을 묻습니다. 승인 요청을 알림으로 받으려면 허용하세요.
• 설정 › 연결의 앱을 닫아도 호스트와 연결 유지는 기본으로 켜져 있습니다. 앱을 닫아도 호스트와 연결을 유지하며 알림을 받고, 그동안 상단에 작은 알림이 하나 떠 있습니다.
• 설정 › 알림에서 승인 요청, 질문, 세션 완료 알림을 각각 켜고 끕니다. 세션 완료 알림은 기본으로 꺼져 있습니다.

Windows 앱

Microsoft Store에서 Foreman을 받습니다. Windows 10 버전 2004 이상(x64)에서 동작합니다. 왼쪽 메뉴에 현황, 승인, 세션, 레이스, 에이전트와 페어링한 호스트 목록이 있고, 맨 아래에 설정이 있습니다.

• 창을 닫으면 앱은 끝나지 않고 알림 영역(트레이)으로 들어갑니다. 트레이 아이콘의 메뉴에서 Foreman 열기와 끝내기를 고릅니다.
• 승인 알림은 앱이 켜져 있어야 받습니다. 로그인할 때 트레이에서 시작하도록 Windows 설정 › 앱 › 시작 프로그램에서 Foreman을 켜 두세요.
• 단축키: Ctrl+N 새 세션, Ctrl+K 검색, Ctrl+] 다음 승인 요청이 있는 세션으로 이동.

02페어링

앱은 페어링한 호스트에만 연결합니다. 페어링할 때 양쪽이 서로의 키를 확인하고, 그 뒤의 모든 연결은 처음부터 끝까지 암호화됩니다.

QR 코드로 연결

1. 호스트 Mac의 메뉴 막대에서 Foreman Host › 다른 기기와 페어링…을 엽니다. Windows 호스트에서는 PowerShell에서 foreman pair를 실행합니다. 터미널에 QR 코드와 링크가 나옵니다.
2. 기기에서 페어링 화면을 열고 QR 코드를 비추거나 링크를 붙여 넣습니다.
3. 코드는 한 번만 쓸 수 있고 5분 뒤 만료됩니다. 만료됐다면 호스트에서 새 코드를 누르거나 foreman pair를 다시 실행합니다.

6자리 확인 코드

연결이 열리면 호스트와 기기에 같은 여섯 자리 숫자(예: 491 795)가 나옵니다. 이 숫자는 두 기기가 주고받은 암호 키에서 계산되므로, 중간에 누가 끼어들면 숫자가 달라집니다.

1. 기기에 “호스트 화면의 숫자와 같나요?”가, 호스트에는 기기 화면의 숫자와 같은지 묻는 창이 뜹니다.
2. 두 숫자가 같으면 양쪽에서 확인을 누릅니다. iPhone·iPad·Mac에서는 같아요, Android와 Windows 앱에서는 같다입니다. foreman pair에서는 y를 입력합니다.
3. 양쪽이 모두 확인해야 페어링이 끝납니다. 기기에 “…와 페어링했어요”가 나오면 완료입니다. 이후에는 호스트가 켜져 있는 한 앱을 열 때마다 자동으로 연결됩니다.

숫자가 다르면 달라요(Android·Windows 앱에서는 다르다)를 누르세요. 페어링하지 않고 끝납니다. 누군가 연결 중간에 끼어든 경우일 수 있으니, 새 코드로 다시 시작하기 전에 네트워크를 확인하세요.

여러 호스트와 연결 상태

한 앱에 호스트를 여러 대 페어링할 수 있습니다. 호스트마다 위의 과정을 한 번씩 거칩니다. 호스트 탭(Windows 앱은 왼쪽 메뉴)에서 각 호스트의 상태를 봅니다.

호스트를 누르면 연결 경로, 켜진 지, 암호화 방식(Noise XX · 종단간)을 볼 수 있습니다. Android와 Windows 앱에서는 호스트 키 지문과 이 기기 키 지문, 호스트 버전도 함께 나옵니다.

기기 관리와 폐기

호스트 Mac의 Foreman Host › 기기 관리…에서 이 호스트에 페어링된 기기와 키 지문, 지금 연결됐는지를 봅니다. 잃어버린 기기나 더 쓰지 않는 기기는 폐기를 누릅니다. 페어링이 바로 해제되고 열려 있던 연결도 끊깁니다. Windows 호스트에서는 foreman devices로 목록을 보고 foreman devices revoke <id>로 폐기합니다.

앱에서 호스트 지우기

iPhone·iPad에서는 호스트를 열고 이 호스트와의 페어링 해제를, Android에서는 이 기기에서 호스트 지우기를, Windows 앱에서는 이 PC에서 지우기를 누릅니다. 이 기기에 저장된 호스트 키와 주소가 지워집니다. 호스트 쪽의 기기 목록은 그대로이므로, 완전히 정리하려면 호스트에서도 이 기기를 폐기하세요.

03클라우드 연결

호스트를 내 iCloud 계정에 연결하면 iPhone·iPad 앱이 꺼져 있어도 승인 요청이 알림으로 오고, 집 밖에서도 호스트에 연결됩니다(집 밖에서 연결). 연결은 호스트에서 한 번만 합니다. 호스트는 그 컴퓨터에 로그인된 iCloud 계정을 쓰지 않고, 브라우저에서 로그인한 계정만 씁니다. 그래서 다른 사람의 컴퓨터를 호스트로 써도 같은 방식으로 동작합니다.

호스트에서 iCloud 연결

Mac 호스트

1. 메뉴 막대에서 Foreman Host › iCloud·Google 연결…을 엽니다. “클라우드 연결” 창이 뜹니다.
2. iCloud 줄의 연결…을 누르면 브라우저에 Apple 로그인 페이지가 열립니다.
3. iPhone에서 쓰는 것과 같은 Apple ID로 로그인합니다. 로그인 상태 유지를 체크하면 몇 주 동안 다시 묻지 않습니다.
4. 브라우저에 “iCloud에 연결했어요. 이 탭을 닫아도 됩니다.”가 나오면 탭을 닫습니다. 창의 iCloud 줄이 “연결됨”으로, “원격 연결”이 “iCloud”로 바뀝니다.

iPhone·iPad 앱은 iCloud를 통해 연결하므로 iCloud를 연결하면 됩니다. 로그인 페이지를 닫아 버렸다면 창의 로그인 페이지 다시 열기를 누릅니다.

Windows 호스트

foreman cloud login icloud

브라우저에 Apple 로그인 페이지가 열립니다. Mac과 같이 iPhone의 Apple ID로 로그인하고 “로그인 상태 유지”를 체크합니다. 로그인이 끝나면 터미널에 iCloud: connected가 나옵니다. 브라우저가 열리지 않으면 터미널에 나온 주소를 직접 엽니다(--no-browser를 붙이면 처음부터 주소만 보여 줍니다). 상태는 foreman cloud로 확인합니다.

로그인 토큰은 호스트의 안전한 저장소(Mac은 키체인, Windows는 DPAPI)에만 들어가고, 파일로 남지 않습니다.

iPhone · iPad에서 확인

iPhone과 iPad는 기기의 iCloud 계정을 그대로 씁니다. 앱 안에서 따로 로그인하지 않습니다. 기기 설정에서 호스트에 연결한 것과 같은 Apple ID로 iCloud에 로그인돼 있는지 확인하세요.

1. Foreman 앱에서 설정 › iCloud 연결을 엽니다.
2. 상태의 “iCloud 계정”이 사용 가능인지 봅니다. “iCloud에 로그인되어 있지 않아요”라면 기기 설정에서 iCloud에 로그인합니다.
3. “푸시 구독”이 켜짐이면 준비가 끝났습니다. 꺼짐이라면 알림 구독 켜기를 누릅니다. 이제 앱이 꺼져 있어도 호스트의 승인 요청이 알림으로 옵니다.

알림은 기기별 키로 암호화된 채 iCloud를 거쳐 오고, iPhone에서 풀어 보여 줍니다. 시험 측정에서 호스트가 보낸 알림은 앱이 꺼져 있을 때도 0.4~1초 안에 iPhone에 닿았습니다.

다시 로그인과 연결 해제

로그인이 만료되면 iCloud를 거치는 경로만 잠시 멈추고, 같은 네트워크에서의 연결은 그대로 됩니다. 이때 iPhone 앱의 설정 › iCloud에 다시 로그인하라는 안내가 뜨고, Foreman Host 메뉴의 iCloud·Google 연결… 옆에 “다시 로그인”이 표시됩니다.

• Mac: 클라우드 연결 창에서 다시 로그인을 누르고 브라우저에서 다시 로그인합니다.
• Windows: foreman cloud login icloud를 다시 실행합니다.
• iPhone에서 로그인해 호스트에 넘겨줄 수는 없습니다. 로그인은 늘 호스트에서 합니다.

연결을 끊으려면 Mac은 창의 연결 해제를, Windows는 foreman cloud logout icloud를 씁니다. 호스트에 저장된 토큰이 지워지고 iCloud를 거치는 경로가 꺼집니다.

클라우드에 저장되는 것

Foreman은 내 iCloud 개인 데이터베이스 안의 Foreman 전용 영역만 씁니다. 저장 공간은 내 iCloud 용량에서 쓰이고, 개발자는 이 데이터를 볼 수 없습니다.

04집 밖에서 연결

호스트가 iCloud에 연결돼 있으면 iPhone·iPad 앱은 같은 Wi-Fi가 아니어도 호스트에 연결합니다. 따로 설정할 것은 없습니다. 앱이 가능한 경로를 한꺼번에 시도하고 가장 빠른 경로를 씁니다.

연결 경로

호스트 목록과 호스트 상세의 “연결”에 지금 쓰는 경로가 나옵니다.

느린 경로로 연결된 동안에도 앱은 더 빠른 경로를 계속 시도하고, 열리면 출력을 잃지 않고 옮겨 갑니다. 어느 경로든 Noise로 처음부터 끝까지 암호화되므로, 공유기나 iCloud에서는 암호문만 보입니다. 시험 측정에서 P2P 연결은 1초 안에 열렸습니다.

연결 확인

• 앱: 호스트를 누르면 “연결”에 지금 경로가 나옵니다. Android와 Windows 앱은 “경로”와 “최근 주소”, “마지막 메시지”를 보여 줍니다.
• Mac 호스트: Foreman Host 메뉴 맨 위 줄과 클라우드 연결 창의 “원격 연결”에 iCloud 연결 여부가 나옵니다.
• 호스트 명령: foreman status의 “원격 연결” 줄에 연결된 클라우드와, 공유기 포트 열기(UPnP·NAT-PMP·PCP)에 성공했는지가 나옵니다. 예: 원격 연결: iCloud (매핑 upnp 203.0.113.9:7878)

05에이전트 연결

지원하는 에이전트

터미널에서 평소처럼 실행하기

셸 연동을 켜 두면 터미널에서 claude, codex, gemini, opencode를 평소처럼 실행해도 Foreman 세션으로 들어옵니다. 앱에서 바로 보이고, 터미널을 닫아도 세션은 호스트에서 계속 돕니다.

Mac (zsh)

/Applications/ForemanHost.app/Contents/MacOS/foreman shim install

~/.zshrc에 Foreman 표시가 붙은 블록이 추가되고, 원래 파일은 .foreman-backup-날짜로 백업됩니다. 새 터미널을 열면(또는 exec zsh) 적용됩니다.

Windows (PowerShell)

foreman shim install

PowerShell 프로필에 같은 블록이 추가됩니다. 새 PowerShell 창부터 적용됩니다. 실행 정책이 Restricted나 AllSigned라면 안내에 따라 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned를 직접 실행하세요. Foreman이 정책을 바꾸지는 않습니다.

• 한 번만 Foreman 없이 실행하려면 command claude(PowerShell에서는 claude.exe)처럼 실행합니다.
• 특정 에이전트만 연동하려면 foreman shim install claude codex처럼 이름을 붙입니다.
• 상태는 foreman shim status, 해제는 foreman shim uninstall로 합니다.

발견된 에이전트 연결

호스트를 열고 에이전트로 들어가면 연결된 에이전트와 계정, 사용 중인 한도가 보입니다. 호스트에 설치돼 있지만 아직 연결하지 않은 에이전트는 “발견됨”(Android·Windows 앱은 “호스트에서 발견”)에 나오고, 연결을 눌러 추가합니다.

승인 없이 실행하는 에이전트

에이전트를 --dangerously-skip-permissions나 --permission-mode bypassPermissions로 실행하거나 Codex의 승인 정책을 never로 두면, 에이전트가 승인을 묻지 않고 바로 명령을 실행합니다. 이때 Foreman은 에이전트가 하는 일을 보여 줄 수는 있지만 멈출 수는 없습니다. 위험한 작업을 앱에서 막고 싶다면 이 옵션 없이 실행하세요.

Free에서 쓸 수 있는 에이전트

Free에서는 에이전트를 두 종류까지 연결합니다. 세 번째 종류를 터미널에서 실행하면 일반 터미널 세션으로 돌아가며, 대화와 승인은 다루지 않습니다. Pro에서는 제한이 없습니다(Pro).

06승인과 질문

에이전트가 명령을 실행해도 되는지 묻거나 질문하면, 모든 호스트의 요청이 앱의 승인 탭에 모입니다. 답을 기다리는 세션에는 ● 표지가 붙습니다.

승인 인박스

위쪽 필터로 전체, 승인, 질문을 나눠 봅니다. 요청마다 프로젝트, 에이전트, 호스트, 실행하려는 명령이 나오고 거부와 허용 버튼이 있습니다. 홈이나 목록에서는 요청을 밀어서도 허용하거나 거부할 수 있습니다.

위험도

Face ID로 허용

위험한 요청에는 Face ID로 허용 버튼이 나옵니다(Mac은 Touch ID). 본인 확인이 끝나야 허용이 호스트로 갑니다. 확인을 취소하면 “허용하지 않았어요”가 뜨고 요청은 그대로 남습니다. 기기에 암호가 설정돼 있지 않으면 위험한 요청을 허용할 수 없으니, 기기 설정에서 암호를 켜 두세요.

잠금화면과 Live Activity

알림을 길게 누르면 앱을 열지 않고 답할 수 있습니다.

세션이 도는 동안에는 잠금화면과 Dynamic Island에 Live Activity가 떠서 실행 중인 세션 수와 당신 차례 수를 보여 줍니다. 모든 세션이 한가해지고 2분이 지나면 사라집니다. 설정 › 알림 › Live Activity에서 끌 수 있습니다. 홈 화면에는 “Foreman 현황”과 “당신 차례” 위젯을 둘 수 있습니다.

Apple Watch

Watch에서 승인 요청을 받고 거부나 허용을 누릅니다. 되돌릴 수 있는 요청은 두 번 탭 제스처로도 허용합니다. 위험한 요청은 Watch 알림에 거부만 있고, 앱에서는 “손목에서 허용할 수 없어요 · iPhone에서 Face ID”로 표시되니 iPhone에서 처리하세요. 질문에는 선택지 버튼이나 받아쓰기로 답합니다.

Android와 Windows

승인 탭은 같은 구성입니다. 필터는 전체, 승인, 질문, 위험이고, 위험한 요청은 Android에서 지문으로 허용, Windows에서 Windows Hello로 허용을 눌러 본인 확인을 거친 뒤에 허용됩니다. Android의 메뉴에는 보이는 요청 모두 거부가 있습니다.

Android는 설정의 앱을 닫아도 호스트와 연결 유지가 켜져 있어야 앱을 닫은 동안 알림을 받습니다. Windows는 앱이 트레이에서 돌고 있어야 알림(토스트)을 받습니다. 세션 화면에서는 Ctrl+Enter로 허용하고 Ctrl+Backspace로 거부합니다.

질문에 답하기

에이전트가 질문하면 선택지가 버튼으로 나오고, 권장 선택지에는 “권장”이 붙습니다. 원하는 답이 없으면 직접 입력을 누르고 답을 써서 보냅니다. 알림에서는 답장으로 바로 답할 수 있습니다.

자동 허용 규칙

승인 탭 오른쪽 위의 자동 허용 규칙에서 호스트에 저장된 규칙을 봅니다. 규칙에 맞는 요청은 규칙대로 처리되고, 규칙에 없는 요청은 지금처럼 인박스로 옵니다.

Pro에서는 요청 카드 아래의 “… 는 앞으로 자동 허용”을 눌러 같은 종류의 요청을 규칙으로 만들 수 있습니다. 만든 규칙은 호스트에 저장되고 호스트가 판단합니다. Android에서는 규칙을 보고 켜고 끌 수 있습니다.

07세션

세션 탭에는 호스트별로 세션이 모여 있습니다. 세션을 누르면 상세 화면이 열리고, 길게 누르면 터미널로 보기, 명령 복사를 고를 수 있습니다.

대화, 터미널, 변경

세션 화면 위쪽에서 세 가지 보기를 오갑니다.

대화

지시와 답, 에이전트가 읽고 고친 파일, 실행한 명령이 차례로 보입니다. 아래 입력창에 다음 지시를 씁니다. 컨텍스트 사용량과 한도가 위에 표시됩니다.

터미널

호스트의 터미널 화면 그대로입니다. 입력은 그대로 PTY로 갑니다.

변경

이 세션에서 바뀐 파일과 추가·삭제 줄 수, 브랜치를 봅니다.

세션을 멈추려면 더 보기 메뉴의 중단을 누릅니다. 한 번 더 확인한 뒤 에이전트를 멈춥니다.

터미널 보기와 키 막대

터미널 아래 키 막대에 esc tab ctrl ^C ↑ ↓ / |가 있습니다. ctrl은 한 번 누르면 다음 키와 조합됩니다. 같은 세션을 호스트의 터미널과 앱이 함께 볼 수 있고, 함께 보는 중이면 위에 표시됩니다.

새 세션

1. 세션 탭의 새 세션을 누릅니다.
2. 호스트를 고릅니다. 꺼진 호스트는 고를 수 없습니다.
3. 폴더에 호스트에서 작업할 경로(예: ~/Projects/app)를 넣습니다.
4. 에이전트를 고르고 지시에 처음 맡길 일을 씁니다.
5. 필요하면 worktree 격리와 편집 자동 허용을 정하고 시작을 누릅니다. 편집 자동 허용을 켜면 파일 수정은 묻지 않고, 그 밖의 명령은 지금처럼 승인을 받습니다.

worktree 격리

worktree 격리를 켜면(기본값) 호스트가 이 세션만을 위한 git worktree를 만들고 foreman/<세션 ID> 브랜치에서 작업합니다. 원래 작업 폴더는 건드리지 않습니다. 세션이 끝나도 worktree는 지워지지 않으니, 결과를 확인한 뒤 평소처럼 병합하거나 지우세요. git 저장소가 아닌 폴더에서는 이 옵션을 끄고 시작하세요.

검색

세션, 명령, 호스트 이름으로 찾습니다.

iPad와 Mac에서

iPad와 Mac의 관제 그리드는 여러 세션을 한 화면에 펼칩니다. ⌘↩로 가장 오래 기다린 요청을 허용하고 ⌘⌫로 거부합니다. 위험한 요청은 단축키로 허용되지 않습니다. Mac 앱에서는 사이드바에 호스트별 세션이, 가운데에 대화가, 아래 서랍에 터미널이 보입니다.

Android와 Windows에서

• Android: 세션 화면에 대화, 터미널, 변경 탭이 있습니다. 대화 탭의 마이크 버튼으로 지시를 받아쓰고, ⋮ 메뉴의 중단 (Ctrl+C)으로 세션을 멈춥니다. 터미널 키 막대는 iPhone과 같습니다.
• Windows: 세션을 열면 터미널이 먼저 보이고, 아래 입력칸의 내용은 그대로 PTY로 갑니다. Ctrl+1·2·3으로 탭을 바꿉니다.
• 새 세션은 두 앱 모두 호스트, 작업 폴더, 에이전트, 지시, worktree 격리를 정하고 시작합니다.

08Pro

구독하기

iPhone·iPad에서는 설정의 Pro 둘러보기를 누르면 구독 화면이 열립니다. 월간과 연간 중에서 고르며, 가격과 결제는 App Store가 표시하고 처리합니다. Android에서는 설정 › 구독의 Foreman Pro에서 요금제를 고르고 구독하기를 누릅니다. 결제는 Google Play가 처리합니다.

구매 복원과 해지

새 기기에서는 설정의 구매 복원을 누르면 같은 계정의 구독이 돌아오고, 연결된 호스트에도 다시 전달됩니다. iPhone에서는 설정의 구독 관리나 iPhone 설정 › 내 이름 › 구독에서 해지합니다. Android에서는 Google Play의 구독 관리에서 해지합니다. 해지해도 결제한 기간이 끝날 때까지 Pro를 씁니다.

여러 호스트에서 쓰기

Pro는 호스트에 붙습니다. 구매하면 스토어가 서명한 구매 정보가 암호화된 연결로 호스트에 전달되고, 호스트가 스스로 확인합니다. 구독은 페어링한 모든 호스트에 적용되고 호스트 수에는 제한이 없습니다. 그래서 iPhone에서 구독하면 같은 호스트에 연결한 Mac 앱에서도 Pro 기능이 열립니다. iPhone 설정에서는 호스트마다 “Pro · 확인됨”처럼 상태가 나옵니다.

한도 페일오버

에이전트가 사용 한도에 닿으면 같은 지시를 다음 에이전트가 이어 받습니다. iPhone에서는 호스트 › 에이전트의 “한도 페일오버”에서 한도에 닿으면 다음 에이전트로를 켜고, 편집으로 넘길 순서를 정합니다. 예를 들어 Claude 한도가 차면 Codex로 넘기고, 리셋되면 돌아옵니다. Mac에서는 에이전트 연계 화면에서 켭니다. 설정은 호스트에 저장되고 호스트가 실행합니다.

다른 에이전트로 넘기기

진행 중인 세션을 다른 에이전트에게 이어서 맡깁니다. iPhone에서는 세션의 더 보기 메뉴에서, Mac에서는 툴바에서 다른 에이전트로 넘기기를 고르고 에이전트를 정합니다. Mac의 에이전트 연계 화면에서 인계 기록을 볼 수 있습니다.

레이스

같은 일을 두 에이전트에게 동시에 맡기고 결과를 비교합니다. 새 세션에서 에이전트를 둘 이상 고르고 두 에이전트로 레이스를 켠 뒤 시작합니다. 각 에이전트는 따로 worktree에서 작업합니다. 끝나면 iPad와 Mac의 레이스 비교에서 테스트 결과, 변경, 브랜치를 나란히 보고 이 결과 채택이나 모두 버리기를 고릅니다.

한도 리셋 후 자동 재개

한도에 닿아 멈춘 세션을 한도가 리셋되면 자동으로 이어 갑니다. iPhone에서는 승인 탭의 자동 허용 규칙으로 여는 Autopilot 화면의 “한도 리셋”에서 리셋 시 자동 재개를 켭니다. 이 항목은 한도에 닿은 에이전트가 있을 때 나타납니다. Mac에서는 한도가 리셋되면 멈춘 세션 자동 재개를 켭니다.

아침 브리핑

밤사이 끝난 일, 막힌 일, 남은 한도를 한 장으로 정리합니다. Autopilot 화면의 “아침 브리핑”을 켜면 매일 정해진 시각에 호스트가 브리핑을 만들고, iPhone 현황 맨 아래에 요약과 승인·거부 수, 세션별 결과(변경 줄 수, 커밋, 테스트 결과)가 나옵니다.

Free와 Pro의 차이

Pro 기능에는 PRO 표지가 붙어 있고, Free에서 누르면 구독 화면이 열립니다. 요금제 전체 비교는 요금제에 있습니다.

09항상 켜 두기

호스트가 꺼지거나 잠들면 그동안 세션도 멈추고 앱에서 연결할 수 없습니다. 에이전트를 맡겨 두는 컴퓨터는 아래처럼 준비해 두세요.

Mac

• Foreman Host 메뉴의 로그인 시 시작을 켭니다. 로그인할 때마다 호스트가 뜨고, 꺼져도 다시 뜹니다.
• 잠자기 방지 (세션 실행 중)는 기본으로 켜져 있습니다. 세션이 하나라도 도는 동안 Mac이 잠들지 않고, 세션이 없으면 평소처럼 잠듭니다. Foreman Host가 실행 중일 때만 작동합니다.
• Foreman Host 메뉴의 종료는 메뉴 막대 앱만 끝냅니다. 호스트와 세션은 계속 돕니다.
• 자리를 오래 비울 Mac이라면 아래의 상시 가동 점검으로 전원과 로그인 설정까지 확인하세요.

Mac 상시 가동 점검

Foreman Host 메뉴의 상시 가동 점검…을 열면 이 Mac이 아무도 없을 때도 세션을 계속 돌릴 수 있는지 점검합니다. 항목마다 결과(정상, 참고, 주의)와 설명이 나오고, 자동으로 고칠 수 있는 항목에는 “고칠 수 있음”이 붙습니다.

고치기를 누르면 자동으로 고칠 수 있는 항목만 바꿉니다. 전원 설정은 macOS가 관리자 암호를 물어본 뒤에만 바뀝니다. FileVault, 자동 로그인, 덮개, 원격 로그인은 Foreman이 바꾸지 않습니다. FileVault가 켜져 있으면 다시 시작한 뒤 누군가 잠금을 풀 때까지 호스트가 뜨지 않습니다. macOS 26에서는 원격 로그인을 켜 두면 로그인 전에 SSH로 잠금을 풀 수 있습니다. 이때 SSH는 집이나 회사 네트워크, VPN 안에서만 열어 두세요.

터미널에서는 같은 점검을 foreman doctor로, 고치기를 foreman doctor --fix로 합니다(foreman doctor).

Windows

foreman doctor가 아래 항목을 점검하고, 고칠 방법을 그 자리에서 알려 줍니다.

절전

전원에 연결된 동안 절전·최대 절전이 꺼져 있어야 세션이 멈추지 않습니다. 설정 › 시스템 › 전원 및 배터리 › 화면, 절전 및 최대 절전 시간 제한에서 “전원에 연결된 경우” 절전을 “안 함”으로 둡니다.

BitLocker

TPM만으로 잠금을 푸는 설정이면 다시 시작한 뒤 저절로 돌아옵니다. 시작 PIN이나 USB 키를 쓰면 누군가 잠금을 풀 때까지 호스트가 꺼진 상태로 남습니다.

다시 시작 후 로그인

호스트는 로그온해야 시작됩니다. 업데이트 뒤 자동으로 로그인되게 하려면 로그인 옵션의 “업데이트 후 내 로그인 정보를 사용하여 자동으로 설정 완료”를 켭니다.

Windows 업데이트

사용 시간을 설정해 두면 그 시간에는 업데이트로 다시 시작하지 않습니다(최대 18시간). 다시 시작하면 그때 돌던 세션은 끝납니다.

foreman doctor

foreman doctor

점검마다 한 줄씩 결과(ok, info, warn, FAIL)가 나오고, 고칠 것이 있으면 그 아래 →로 방법이 붙습니다. 호스트 데몬 실행 여부와 셸 연동도 함께 확인합니다. warn만 있으면 Foreman은 동작하지만 아무도 없을 때 호스트가 꺼질 수 있다는 뜻입니다.

Mac에서는 foreman doctor --fix로 고칠 수 있는 항목을 보여 주고, 확인을 받은 뒤 바꿉니다. 전원 설정은 관리자 암호 창이 한 번 뜹니다. 터미널이 아닌 곳에서 실행할 때는 --yes를 붙입니다.

10개인정보와 보안

우리 서버 0대

Foreman에는 개발자가 운영하는 중계·계정·로그 서버가 없습니다. 세션 내용은 내 호스트와 내 기기, 그리고 내 iCloud 계정 사이에서만 오가고, 개발자는 아무것도 저장하거나 열람하지 않습니다. 자세한 내용은 개인정보 처리방침에 있습니다.

종단간 암호화

모든 연결은 Noise XX(X25519 · ChaCha20-Poly1305)로 처음부터 끝까지 암호화됩니다. 페어링할 때 호스트 키가 기기에 고정되므로, 다른 키를 내미는 상대에게는 연결하지 않습니다. iCloud를 거치는 경로에서도 iCloud에는 암호문만 남습니다(클라우드에 저장되는 것).

키가 저장되는 곳

11자주 묻는 질문

터미널 창을 닫으면 세션도 끝나나요?

아니요. 세션은 호스트가 소유합니다. Foreman으로 시작한 세션은 터미널을 닫거나 Ctrl+]로 떼어 내도 계속 돌고, foreman attach <id>나 앱으로 다시 붙습니다.

호스트를 다시 시작하면 어떻게 되나요?

호스트 데몬만 다시 시작한 경우에는 세션이 그대로 이어지고 앱도 저절로 다시 연결됩니다. 컴퓨터를 다시 시작하면 그때 돌던 세션은 끝납니다.

밖에서 iPhone으로 호스트에 연결되지 않아요.

호스트가 iCloud에 연결돼 있는지(Mac은 클라우드 연결 창, Windows는 foreman cloud), iPhone이 같은 Apple ID로 iCloud에 로그인돼 있는지 확인하세요. 앱의 설정 › iCloud 연결에서 “iCloud 계정”이 사용 가능인지도 봅니다(클라우드 연결). 호스트가 꺼져 있거나 잠들어 있으면 어떤 경로로도 연결되지 않습니다.

터미널에서 실행한 에이전트가 앱에 안 보여요.

셸 연동이 켜져 있는지 foreman shim status로 확인하고, 연동을 설치한 뒤 새로 연 터미널에서 실행했는지 확인하세요(터미널에서 평소처럼 실행하기). Free에서는 세 번째 종류의 에이전트가 일반 터미널 세션으로 들어옵니다.

위험한 요청을 알림에서 바로 허용할 수 없어요.

의도된 동작입니다. 되돌릴 수 없는 작업은 앱 안에서 본인 확인을 거쳐야만 허용합니다. iPhone 알림의 Face ID로 허용을 누르면 앱이 열리고 Face ID로 확인합니다(Face ID로 허용).

휴대폰을 잃어버렸어요.

호스트의 기기 관리(Windows는 foreman devices revoke <id>)에서 그 기기를 폐기하세요. 바로 연결이 끊기고 다시 연결할 수 없습니다(기기 관리와 폐기).

페어링할 때 숫자가 달라요.

양쪽에서 달라요를 누르고 끝내세요. 네트워크를 확인한 뒤 새 코드로 다시 시작합니다.

다른 문제가 있어요.

지원 페이지의 GitHub Issues로 알려 주세요. 기기와 OS 버전, 그리고 foreman doctor 결과를 함께 보내 주시면 빨리 확인할 수 있습니다. API 키나 토큰은 적지 마세요.

12CLI 참고

호스트에는 foreman 명령이 함께 설치됩니다. Windows에서는 PowerShell에서 바로 foreman으로, Mac에서는 /Applications/ForemanHost.app/Contents/MacOS/foreman로 실행합니다. 대부분의 명령은 --json을 붙이면 기계가 읽을 수 있는 형식으로 답합니다.

세션

페어링과 기기

클라우드

셸 연동

로그온 시 시작

상태와 점검