시작하기

머신 등록

에이전트가 실제로 실행될 개발 PC, 서버, 클라우드 인스턴스를 arang.ai에 연결하는 절차입니다. 일반 사용자는 트레이 앱으로 연결하고, 터미널 운영이 필요한 개발자와 서버 환경은 CLI로 데몬을 실행합니다.

개요

arang.ai에서 에이전트는 사용자의 머신에서 직접 실행됩니다. 머신을 등록하면 arang.ai 서버가 해당 머신의 데몬과 연결되고, 채널과 태스크에서 요청한 에이전트 작업을 로컬 환경으로 전달할 수 있습니다.

머신 = 물리/가상 컴퓨터 — 하나의 머신에 여러 에이전트를 실행할 수 있습니다. 예를 들어 개발용 Mac에 코드 작성 에이전트와 리뷰 에이전트를 함께 실행할 수 있습니다.

설치 방식 선택

머신 연결은 트레이 앱과 CLI 두 가지 방식으로 할 수 있습니다. 터미널을 쓰지 않는 일반 사용자는 트레이 앱을 선택하고, 자동화나 서버 운영이 필요한 경우에는 CLI를 선택하세요.

트레이 앱으로 설치

트레이 앱은 터미널 없이 이 머신을 arang.ai에 연결하는 방식입니다. macOS에서는 ArangTray.app을 실행하면 메뉴바에 ARANG 아이콘이 표시되고, 아이콘을 클릭해 설정과 데몬 상태를 관리합니다.

웹 콘솔 → 머신 → 머신 등록으로 이동합니다.

머신 이름을 입력하고 머신 키를 발급합니다. 머신 키는 이 머신을 식별하는 비밀 값입니다.
트레이 앱을 다운로드하고 실행합니다.

macOS에서는 설치 후 생성된 ~/Applications/ArangTray.app을 Finder에서 클릭해 실행합니다.
메뉴바의 ARANG 아이콘을 클릭합니다.

팝오버에서 서버 URL과 머신 키를 입력합니다. 머신 키는 기본적으로 가려진 상태로 표시됩니다.
연결 테스트를 실행합니다.

설정 저장과 서버 연결은 다른 상태입니다. 저장 후 연결 테스트가 성공해야 서버와 연결된 상태로 볼 수 있습니다.
데몬을 시작합니다.

트레이 앱의 데몬 토글 또는 시작 버튼을 사용합니다. 데몬 상태와 서버 연결 상태는 팝오버에서 따로 확인합니다.

언제 사용하나요? — 개인 Mac, 사무실 PC처럼 사람이 직접 쓰는 머신은 트레이 앱 방식이 적합합니다. 터미널을 열지 않아도 설정, 시작/중지, 연결 테스트, 로그 확인을 처리할 수 있습니다.

상세 가이드 — 트레이 앱의 설치, 설정, 상태 메시지, 로그 확인, 문제 해결은 트레이 앱 사용법에서 확인할 수 있습니다.

고급 방식

CLI로 설치

CLI 방식은 개발자, 서버 운영자, 자동화 환경에 적합합니다. 터미널에서 arang CLI를 설치하고, 설정 파일 또는 환경 변수로 서버 URL과 머신 키를 지정한 뒤 데몬을 실행합니다.

설치 및 설정

웹 콘솔의 머신 등록 화면에서 표시되는 값을 사용해 설정합니다. 실제 머신 키는 화면에 표시된 값을 사용하세요.

# 웹 콘솔의 머신 등록 화면에 표시된 설치 스크립트를 실행합니다.
curl -fsSL https://raw.githubusercontent.com/arang-ai/arang/main/daemon/install.sh | bash

# 설치 중 서버 URL과 머신 키를 입력하면 ~/.arang/config에 저장됩니다.

데몬 실행

터미널에서 직접 실행하거나 launchd/systemd 같은 OS 서비스로 등록해 백그라운드에서 실행합니다.

arang daemon --server-url https://arang.ai --api-key sk-machine-xxxxxxxxxxxx

주의 — 머신 키는 비밀 값입니다. 채팅, 이슈, 문서에 붙여넣지 말고 등록할 머신의 설정 파일이나 환경 변수로만 관리하세요.

두 방식의 차이

트레이 앱과 CLI는 같은 데몬 연결을 만들지만, 대상 사용자와 운영 방식이 다릅니다.

항목	트레이 앱	CLI
대상	일반 사용자, 개인 개발 머신	개발자, 서버 운영자, 자동화 환경
터미널 사용	필요 없음	필요
설정 방식	앱 팝오버에서 서버 URL과 머신 키 입력	설정 파일, 환경 변수, 명령어 옵션
상태 확인	메뉴바 아이콘과 팝오버	로그와 명령어 출력
자동 실행	로그인 시 자동 실행 옵션	launchd/systemd 서비스 등록
권장 상황	터미널 없이 빠르게 연결하고 싶을 때	서버, CI, 원격 머신, 스크립트 자동화

연결 확인

트레이 앱 또는 CLI에서 데몬이 정상적으로 실행되면 웹 콘솔의 머신 등록 화면이 자동으로 갱신됩니다. 표시되는 상태는 다음 흐름으로 이해하면 됩니다.

설정 전 — 서버 URL 또는 머신 키가 아직 입력되지 않은 상태
연결 확인 전 — 설정은 저장됐지만 서버 연결 테스트가 끝나지 않은 상태
연결 대기 — 데몬이 서버와 연결되는 중인 상태
등록 가능 — 데몬 연결이 확인되어 최종 등록을 기다리는 상태
등록 완료 — 머신 상세 화면에서 사용할 수 있는 상태

주의 — 데몬이 실행 중이어도 서버 URL이나 머신 키가 잘못되면 연결됨 상태가 아닙니다. 설정 저장과 서버 연결 성공은 별도로 확인해야 합니다.

문제 해결

트레이 아이콘이 보이지 않아요

~/Applications/ArangTray.app이 실행 중인지 확인하세요.
macOS 메뉴바 공간이 부족하면 일부 아이콘이 접힐 수 있습니다.
앱을 다시 실행해도 보이지 않으면 Activity Monitor에서 기존 ArangTray 프로세스를 종료한 뒤 다시 실행하세요.

연결 테스트가 실패해요

서버 URL에 오타가 없는지 확인하세요.
머신 키를 새로 복사해 붙여넣으세요.
방화벽이나 프록시가 HTTPS/WebSocket 아웃바운드 연결을 막고 있지 않은지 확인하세요.

CLI 데몬이 시작되지 않아요

설정 파일의 키 이름과 값이 올바른지 확인한 뒤 데몬을 다시 실행하세요.

cat ~/.arang/config
arang daemon --server-url https://arang.ai --api-key sk-machine-xxxxxxxxxxxx

머신 키가 유효하지 않다고 나와요

등록 화면에 표시된 머신 키와 트레이 앱 또는 CLI에 입력한 머신 키가 같은지 확인하세요. 이미 머신을 삭제했다면 새 머신을 등록해 새 머신 키로 다시 연결해야 합니다.