TIL: Headless Mode

 

개요

개발을 하다보면 헤드리스 모드(Headless Mode)라는 말을 종종 듣는데 그 뜻을 명확히 알지 못한채 지내왔다. 이번에 Claude Code 관련 유튜브에서 다시금 헤드리스 모드 이야기를 하기에 GPT-5를 이용하여 정리해본다.

TL;DR

• 원래는 GUI(머리, 화면) 없이 프로그램을 실행하는 방식을 뜻한다.
• 브라우저·게임·VM 등 원래 화면이 있어야 하는 프로그램을 백그라운드에서 자동화·테스트용으로 돌릴 때 자주 쓰인다.
• 비인터랙티브(non-interactive) 모드, 즉 입력이 없이 한 번 실행하는 경우와 비슷하지만, 헤드리스 모드는 “화면 없음”에, 비인터랙티브는 “사용자 개입 없음”에 강조점이 있다.
• Claude Code에서 claude -p 실행을 헤드리스 모드라 부르는 것도 같은 맥락으로, 대화형 UI 없이 자동화 환경에서 쓴다는 의미이다.

헤드리스 모드 - 개념과 어원

• 원래는 머리(head = 모니터, 디스플레이, GUI) 가 없는 상태를 말한다.
• 유래를 보면
  • 70~80년대 서버/미니컴퓨터 시절, 모니터 없이 돌리는 컴퓨터 환경을 “headless”라 불렀음.
  • 리눅스/유닉스 전통에서는 GUI(X11 등) 없이 CLI로만 동작하는 서버를 “headless server”라고 불렀음.
  • 이후 브라우저, 게임 엔진, 가상머신 등 GUI가 기본인 프로그램을 화면 없이 실행할 때도 이 표현이 확장되어 쓰였음.

일반적인 활용 사례

1. 웹 브라우저 자동화 (Selenium, Playwright 등)

• 헤드리스 모드: 브라우저 창 없이 백그라운드에서 동작한다. 덕분에 속도가 빠르고, CI/CD에서 GUI가 불필요하다.
• 인터랙티브 모드: 실제 브라우저 창을 띄우고 과정을 눈으로 볼 수 있다. 따라서 디버깅에 유리하다.

2. 게임/그래픽 엔진

• 헤드리스 모드: 그래픽 화면 없이 서버에서 물리 엔진, AI 연산만 실행한다.
• 인터랙티브 모드: 실제 그래픽 창을 통해 사용자가 직접 조작한다.

3. 서버 환경 (리눅스/유닉스)

• 헤드리스 환경: 모니터/GUI 없이 CLI만으로 작동한다.
• 인터랙티브 환경: 사용자가 직접 터미널에서 입력·출력하며 조작한다.

4. 가상 머신 / 컨테이너

• 헤드리스 VM: 가상머신이 GUI 창 없이 백그라운드에서 실행한다.
• 인터랙티브 VM: GUI 창을 띄워서 사용자가 직접 다룬다.

5. 빌드·테스트 자동화 (CI/CD)

• 헤드리스 실행: 자동화 서버에서는 UI가 필요 없으므로 항상 headless 모드로 테스트를 수행한다.

비인터랙티브 모드와의 구분

• 비인터랙티브 모드(non-interactive mode): 사용자 개입 없이 명령 한 번에 한 번 실행한다.
  • 예) grep, curl, claude -p "프롬프트".
• 헤드리스 모드(headless mode):
  • 원래 GUI가 있어야 하는 프로그램을 화면 없이 실행하는 맥락을 말한다.
  • 하지만 일부 도구(예: Claude Code)는 대화형 인터페이스가 없는 실행 방식까지 포함해 headless라 부르기도 한다.

Claude Code의 Headless Mode

Anthropic의 Claude Code에서는 CLI 실행 시 다음과 같은 의미로 headless mode를 정의한다.

• 자동화, CI 파이프라인, pre-commit hook, 빌드 스크립트, GitHub 이벤트 처리 등 사람의 눈으로 대화형 세션을 볼 필요 없는 환경에서 사용한다.
• p "프롬프트" 옵션으로 단일 실행하고, -output-format stream-json 옵션으로 JSON 스트림 결과를 받아 기계 처리가 가능하다.
• 세션 지속성 없어 매 실행마다 새로 시작한다.

즉, Claude Code의 맥락에서 claude -p 실행은 “비인터랙티브 실행”이자, Anthropic이 정의한 “headless mode”에 해당한다.

마무리

“헤드리스 모드”라는 표현은 화면 없는 실행에서 출발했고, 지금은 자동화, 서버 실행, 비대화형 실행을 포괄하는 의미로 넓게 쓰이고 있다.