시작하기

트레이 앱 사용법

ARANG 트레이 앱을 사용하면 터미널 없이도 데몬을 시작하고, 에이전트 상태를 확인하고, 서버 연결을 관리할 수 있습니다. 이 문서에서는 설치부터 일상 사용까지 단계별로 안내합니다.

트레이 앱이란?

트레이 앱은 macOS 메뉴바에 상주하는 작은 앱입니다. 아이콘을 클릭하면 데몬 상태를 확인하고 시작/중지/재시작할 수 있는 패널이 열립니다.

트레이 앱으로 할 수 있는 것:

데몬 시작, 중지, 재시작
에이전트 온라인 상태 확인
서버 URL과 머신 키 설정
실시간 로그 확인
웹 콘솔 바로가기

지원 환경 — 현재 macOS 13 이상을 지원합니다. Windows와 Linux 버전은 준비 중입니다.

설치하기

트레이 앱 설치는 머신 등록 문서의 "트레이 앱으로 설치" 섹션에서 안내합니다.

설치가 끝나면 ~/Applications/ArangTray.app을 실행하세요. 메뉴바에 ARANG 아이콘이 나타납니다.

처음 설정하기

처음 실행하면 서버 연결 정보를 입력해야 합니다.

메뉴바의 ARANG 아이콘을 클릭합니다.
설정...을 선택합니다.
서버 URL을 입력합니다.
- 워크스페이스 관리자에게 확인하세요. (예: https://arang.ai)
머신 키를 입력합니다.
- 웹 콘솔의 머신 관리 페이지에서 발급받을 수 있습니다.
연결 테스트 버튼을 눌러 연결이 되는지 확인합니다.
저장을 누르면 데몬이 자동으로 시작됩니다.

설정이 완료되면 메뉴바 아이콘 옆에 초록색 점이 표시되고, "실행 중" 상태가 됩니다.

기본 사용법

메뉴바의 ARANG 아이콘을 클릭하면 다음 항목들이 표시됩니다.

상태 확인

맨 위에 데몬 상태가 표시됩니다. 초록색 점은 정상, 빨간색 점은 중지 또는 연결 오류를 뜻합니다.

표시	의미
🟢 실행 중	데몬이 서버에 정상 연결되어 있습니다.
🔴 중지됨	데몬이 꺼져 있습니다. 토글을 켜면 시작합니다.
🔴 연결 실패: ...	데몬은 실행 중이지만 서버에 연결하지 못했습니다. 메시지를 확인하세요.

에이전트 온라인 수

"에이전트 N/M 온라인"은 현재 온라인 에이전트 수와 등록된 총 에이전트 수를 보여줍니다. 클릭하면 웹 콘솔의 머신 상세 페이지로 이동합니다.

시작/중지

오른쪽 토글 스위치로 데몬을 시작하거나 중지할 수 있습니다. 앱을 실행하면 이전 설정이 있을 경우 데몬이 자동으로 시작됩니다.

메뉴 항목

항목	설명
설정...	서버 URL, 머신 키, 자동 시작, 언어를 변경합니다.
재시작	데몬을 중지했다가 다시 시작합니다. (실행 중일 때만 표시)
arang.ai 열기	웹 브라우저에서 서버를 엽니다.
로그 보기	데몬 로그를 실시간으로 볼 수 있는 창을 엽니다.
종료	데몬을 중지하고 트레이 앱을 종료합니다.

설정 변경하기

설정...을 클릭하면 설정 창이 열립니다.

항목	설명
서버 URL	ARANG 서버 주소입니다.
머신 키	서버에서 발급받은 머신 등록 키입니다. 비밀번호처럼 가려져 표시됩니다.
연결 테스트	입력한 서버 URL과 머신 키로 연결을 시도합니다.
로그인 시 자동 시작	macOS 로그인할 때 트레이 앱을 자동으로 시작합니다.
언어	한국어, English, 시스템 언어 중 선택할 수 있습니다.

서버 URL이나 머신 키를 변경하고 저장을 누르면 데몬이 자동으로 재시작됩니다.

로그 확인하기

로그 보기를 클릭하면 데몬 로그를 실시간으로 볼 수 있는 창이 열립니다.

새로운 로그가 추가되면 자동으로 아래로 스크롤됩니다.
에러 메시지는 빨간색, 경고 메시지는 주황색으로 표시됩니다.
텍스트를 선택하고 복사할 수 있습니다.
API 키 같은 민감한 정보는 자동으로 가려집니다.

연결 문제가 발생했을 때 로그를 확인하면 원인을 빠르게 파악할 수 있습니다.

언어 변경하기

설정 창에서 원하는 언어를 선택할 수 있습니다.

옵션	설명
시스템 언어	macOS 시스템 언어를 따릅니다. 한국어가 아니면 영어로 표시됩니다.
한국어	모든 메뉴와 메시지가 한국어로 표시됩니다.
English	모든 메뉴와 메시지가 영어로 표시됩니다.

저장을 누르면 즉시 반영됩니다. 앱을 다시 시작할 필요가 없습니다.

자주 묻는 질문

데몬이 시작되지 않아요

설정에서 서버 URL과 머신 키가 올바르게 입력되어 있는지 확인하세요. 연결 테스트를 눌러 서버에 연결되는지 확인할 수 있습니다. 이미 다른 데몬이 실행 중인 경우에도 시작되지 않을 수 있습니다.

"연결 실패: 서버 주소를 확인하세요" 라고 표시돼요

서버 URL이 올바른지 확인하세요. 오타가 있거나 서버가 다운되어 있을 수 있습니다. URL 앞에 https://가 포함되어 있는지도 확인하세요.

"연결 실패: 머신 키를 확인하세요" 라고 표시돼요

머신 키가 서버에 등록된 키와 일치하는지 확인하세요. 웹 콘솔의 머신 관리 페이지에서 키를 다시 확인하거나 재발급받을 수 있습니다.

에이전트가 0/N 온라인으로 표시돼요

데몬이 방금 시작된 경우 에이전트가 아직 실행되지 않았을 수 있습니다. 잠시 기다리면 에이전트가 순차적으로 시작됩니다. 계속 0이면 로그를 확인하여 에이전트 시작 오류가 있는지 살펴보세요.

설정 창을 닫으면 다른 앱이 앞으로 나와요

최신 버전에서는 설정 창을 닫으면 이전에 사용하던 앱으로 자동 복귀합니다. 문제가 계속되면 트레이 앱을 최신 버전으로 업데이트하세요.

macOS 권한 팝업이 떠요

최신 버전에서는 불필요한 권한 요청이 발생하지 않습니다. 팝업이 뜨면 "허용 안 함"을 선택하고 트레이 앱을 최신 버전으로 업데이트하세요.