12.7. 헤드리스 모드¶
"헤드리스 모드"는 그래픽 사용자 인터페이스(GUI)에 의존하지 않고, Backend.AI GO를 주로 백그라운드 서비스나 서버로 실행하는 방식을 말합니다. 이는 유휴 장비를 전용 추론 서버로 설정하거나 원격에서 애플리케이션을 관리할 때 특히 유용합니다.
개념¶
Backend.AI GO는 데스크톱 애플리케이션으로도 제공되지만, 핵심 런타임은 공용으로 설계되어 있습니다:
- 공용 Rust 런타임: 모델 추론, 프로세스 오케스트레이션, Management API, Continuum Router를 처리합니다.
- 데스크톱 전송 계층: 내장 WebView에서 Tauri IPC를 사용합니다.
- 헤드리스 전송 계층:
aigo-server가 제공하는 REST 및 SSE, 그리고 HTTP로 제공되는 WebUI를 사용합니다.
즉, 실제 데스크톱 통합(시스템 트레이, 네이티브 창 등)이 필요한 기능을 제외하면, 헤드리스 WebUI와 데스크톱 UI는 동일한 런타임 로직을 실행합니다.
운영 방법¶
시스템 트레이 (System Tray)¶
가장 기본적인 "헤드리스 스타일" 운영은 메인 창을 닫는 것입니다. * 기본적으로 창을 닫으면 Backend.AI GO는 시스템 트레이(macOS의 경우 메뉴 막대)로 최소화됩니다. * 이 상태에서도 API 서버와 모델 추론 프로세스는 백그라운드에서 계속 실행됩니다.
CLI 제어¶
함께 제공되는 aigo CLI를 사용하면 창을 열지 않고도 애플리케이션을 관리할 수 있습니다.
# 로드된 모델 목록 확인
aigo model list
# 모델 로드
aigo model load --name "llama-3-8b-instruct"
# 시스템 상태 확인
aigo system info
자세한 내용은 CLI 참조(CLI Reference) 문서를 확인하세요.
전용 헤드리스 서버 (aigo-server)¶
Backend.AI GO는 독립 실행형 헤드리스 바이너리를 제공합니다:
이 모드에서는 다음과 같이 동작합니다:
aigo-server의 dependency graph에tauricrate가 포함되지 않습니다.- Management API가 주요 제어 평면이 됩니다.
- WebUI는 Tauri IPC 대신 HTTP/SSE로 연결됩니다.
- 모델 풀, 라우터 관리, 스케줄링, 에이전트, 메모리, provider/runtime coordination은 데스크톱 앱과 동일한 공용 런타임 매니저를 재사용합니다.
원격 접속 (서버 모드)¶
로컬 컴퓨터를 다른 사용자를 위한 헤드리스 노드로 전환하려면:
- 설정 > 고급으로 이동합니다.
- 원격 접속 허용을 활성화합니다.
- API 포트를 설정합니다 (기본값: 8080).
- (선택 사항) 해당 포트에 대한 방화벽 규칙을 설정합니다.
이제 다른 Backend.AI GO 인스턴스, WebUI, 또는 curl/Python 스크립트가 사용자의 컴퓨터 IP 주소로 연결하여 마치 서버처럼 사용할 수 있습니다.
최초 실행 로그인 (aigo-server)¶
기존 데이터 없이 aigo-server가 처음 시작되면 http://<host>:8001에서 초기 설정 화면을 제공합니다. 브라우저로 접속한 뒤 관리자 계정의 사용자 이름과 비밀번호를 설정하면 즉시 로그인됩니다. 이후 방문 시에는 로그인 화면이 표시됩니다.
서버가 로컬이 아닌 인터페이스에 바인딩되어 있으면 최초 설정에 설정 토큰도 필요합니다. per-user 관리 서비스는 임의의 AIGO_SETUP_TOKEN을 생성해 서버를 시작하고, 사용자의 브라우저를 /#setupToken=<token> 형태로 열어 설정 폼이 자동으로 채워지게 해야 합니다. 운영자는 aigo-server 시작 로그에 한 번 출력되는 설정 토큰을 직접 복사할 수도 있습니다. localhost 전용 최초 설정에는 이 토큰이 필요하지 않습니다.
SDK 클라이언트(curl, Python 등)는 로그인 후 설정 > API 키에서 생성한 액세스 키와 X-API-Key 또는 Authorization: Bearer 헤더를 사용합니다.
문제 해결¶
API 키 저장 위치¶
헤드리스 모드에서는 GUI가 필요한 OS 키체인 대신 암호화된 파일(encrypted_keys.json)에 API 키를 저장하며, 서버를 재시작해도 키는 그대로 유지됩니다.