시작하기

Alpacon CLI는 터미널 환경에서 Alpacon 서비스를 관리할 수 있는 명령줄 기반 도구입니다. 본 가이드는 CLI 설치, 서버 등록, websh 접속까지의 절차를 순차적으로 다룹니다.

1. 사전 준비사항

다음 조건을 충족했는지 먼저 확인하세요:

  • Alpacon Server가 실행 중일 것
  • Alpacon Server에 Alpamon Agent가 설치되어 작동 중일 것

2. 설치

Alpacon CLI는 운영체제별로 다양한 방법으로 설치할 수 있습니다. 아래에서 사용하는 환경에 맞는 탭을 선택하여 설치를 진행하세요.

AI에게 맡기고 싶다면? 아래 프롬프트를 Claude, Cursor 등 AI 도구에 복사해 붙여넣으세요. 사용자의 기기에서 실행되는 어시스턴트(예: Claude Code)는 OS를 자동으로 감지해 단계를 실행할 수 있고, 채팅에서는 사용하는 OS만 알려주면 됩니다.

내 기기에 Alpacon CLI를 설치해줘. 공식 가이드(https://docs.alpacax.com/reference/cli/getting-started/)의 설치 단계를 따라, 내 OS(Linux, macOS, Windows)를 감지하거나 내가 알려주는 OS를 기준으로 실행하고, 끝나면 `alpacon version`으로 확인해줘.

Ubuntu / Debian

curl -s https://packagecloud.io/install/repositories/alpacax/alpacon/script.deb.sh?any=true | sudo bash
sudo apt-get install alpacon

CentOS / RHEL

curl -s https://packagecloud.io/install/repositories/alpacax/alpacon/script.rpm.sh?any=true | sudo bash
sudo yum install alpacon

GitHub Releases

VERSION=<최신버전>
wget https://github.com/alpacax/alpacon-cli/releases/download/${VERSION}/alpacon-${VERSION}-linux-amd64.tar.gz
tar -xvf alpacon-${VERSION}-linux-amd64.tar.gz
chmod +x alpacon
sudo mv alpacon /usr/local/bin

💡 각 설치 방법에 대한 최신 정보는 공식 GitHub 저장소를 참고하세요.

3. 로그인 및 로그아웃

Alpacon CLI의 모든 기능을 사용하려면 먼저 Alpacon API에 인증해야 합니다.

로그인

Alpacon Cloud는 워크스페이스 이름과 리전으로 로그인하거나, 인자 없이 alpacon login을 실행하여 대화형으로 입력할 수 있습니다. **자체 호스팅(Self-hosted)**은 호스트를 인자로 전달합니다.

# Alpacon Cloud (interactive)
alpacon login
 
# Alpacon Cloud (non-interactive)
alpacon login --workspace myworkspace --region us1
 
# Alpacon Cloud with an API token
alpacon login --workspace myworkspace --region us1 -t apikey1234
 
# Self-hosted
alpacon login alpacon.example.com

Alpacon Cloud 브라우저 로그인(API 토큰을 사용하지 않는 경우)은 브라우저를 통해 인증이 진행됩니다. CLI에 표시되는 URL을 브라우저에서 열어주세요:

Logging in to https://myworkspace.ap1.alpacon.io

==================== AUTHENTICATION REQUIRED ====================

Please authenticate by visiting the following URL:
https://auth.alpacon.io/activate?user_code=BBHT-GNKB

===============================================================

해당 링크를 브라우저에서 열어 인증을 완료하세요 (워크스페이스에 MFA가 설정된 경우 MFA 인증도 포함됩니다).

재로그인

재로그인 시 config.json에 저장된 기존 워크스페이스 URL이 자동으로 재사용됩니다:

alpacon login  # Uses saved workspace URL

다른 워크스페이스로 로그인하려면 명령어에 --workspace와 --region(Alpacon Cloud) 또는 새로운 호스트(자체 호스팅)를 지정하세요.

워크스페이스 관리

Auth0를 통해 로그인한 경우, 재인증 없이 워크스페이스를 조회하고 전환할 수 있습니다:

# 현재 워크스페이스 확인
alpacon workspace
 
# 사용 가능한 워크스페이스 목록 조회
alpacon workspace ls
 
# 다른 워크스페이스로 전환
alpacon workspace switch other-workspace

워크스페이스 전환은 리전 간에도 가능합니다 (예: us1에서 ap1으로). 워크스페이스 목록은 로그인 토큰에서 추출되며, 별도의 API 호출이 필요하지 않습니다.

로그아웃

alpacon logout

멀티 워크스페이스 모드인 경우, 로그아웃하면 계정에 연결된 모든 워크스페이스의 세션이 종료됩니다.

config.json

로그인에 성공하면 다음 경로에 설정 파일이 자동으로 생성됩니다:

~/.alpacon/config.json              # Linux, macOS
%USERPROFILE%\.alpacon\config.json  # Windows

이 파일에는 다음 정보가 포함됩니다:

  • 워크스페이스 URL 및 이름
  • 인증 토큰
  • 베이스 도메인 (멀티 워크스페이스 지원용)

해당 파일은 Alpacon CLI가 명령어를 실행할 때 필수적으로 사용되며, 토큰이 만료되면 다시 로그인해야 합니다.

alpacon logout 명령을 실행하면 이 config.json 파일은 삭제되며, 이후 명령어 실행을 위해 다시 로그인이 필요합니다.

4. 서버 목록 조회

워크스페이스에 등록된 서버 목록을 확인하려면 다음 명령어를 실행하세요.

alpacon server ls / list

5. 작업 세션 생성

브라우저 로그인으로 인증한 경우, websh, exec, cp, tunnel 같은 접근 명령을 실행하려면 활성 작업 세션이 필요합니다. 토큰 인증(API 토큰)은 이 요구 사항을 우회합니다.

현재 인증에 작업 세션이 필요한지 확인하세요.

alpacon whoami

필요하다면 세션 생성, 승인 대기, 활성 세션 지정을 한 번에 처리하세요.

alpacon work-session create --purpose "server check" --scope websh \
  --server my-server --expires-in 1h --wait --use

이후 접근 명령은 이 세션에 자동으로 연결됩니다. 전체 워크플로는 alpacon work-session 레퍼런스를 참고하세요.

6. Websh 접속

서버의 Websh 터미널에 접속하려면 다음 명령어를 사용하세요.

CONNECTED 상태가 true인 서버만 접속할 수 있습니다.

기본 접속

alpacon websh [SERVER NAME]

root 권한으로 접속

root권한으로도 접속할 수 있습니다.

alpacon websh root@[SERVER NAME]

접속 종료

exit

더 알아보기

이제 Alpacon CLI의 기본 사용법을 익히셨습니다.
다양한 명령어를 통해 Alpacon 서비스를 더욱 강력하게 활용해보세요.

자세한 명령어는 CLI 전체 명령어 문서에서 확인하실 수 있습니다.

최종 수정: