---
title: "Alpamon 설치"
description: "지원되는 Linux, macOS, Windows 서버에 Alpamon을 설치하고 워크스페이스에 등록합니다. 생성된 설치 명령을 사용하거나 플랫폼에 맞는 수동 방법을 선택하세요. 등록 결과를 확인하고, 인증서나 프록시 등 별도 구성이 필요할 때 참고할 자료도 찾을 수 있습니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# Alpamon 설치

<span id="설치-가이드" />

# Alpamon 설치

서버에 Alpacon 에이전트(Alpamon)를 설치하고 워크스페이스에 연결하는 방법을 알아봅니다.

## 사전 요구사항

Alpacon을 설치하기 전에 다음을 확인하세요:

- **Alpacon 워크스페이스**: 없다면 [데모를 신청](https://www.alpacax.com/kr/pricing/?utm_source=docs)해 AlpacaX 팀과 함께 설정하거나 관리자에게 초대를 요청하세요
- **서버 요구사항**:
  - 지원되는 OS ([지원 플랫폼](#지원-플랫폼) 참조)
  - 설치를 위한 root 또는 sudo 접근 권한
  - 아웃바운드 HTTPS 연결 (포트 443)
  - 150MB 여유 디스크 공간
  - 128MB 사용 가능한 RAM

## 지원 플랫폼

운영체제와 아키텍처는 [지원 플랫폼](/reference/platforms/)에서 확인하세요.

### 플랫폼별 기능 범위

플랫폼에 따라 다른 기능은 [Windows 기능 표](/reference/platforms/windows/#windows에서-사용할-수-있는-기능)를 참고하세요.

## 빠른 설치

Alpamon을 설치하고 등록하는 권장 방법입니다.

### 1단계: 워크스페이스에서 서버 등록 준비

1. Alpacon 워크스페이스에 로그인
2. **Servers** → **서버 등록**으로 이동한 뒤 **토큰으로 등록** 선택
3. **서버의 OS는 무엇인가요?**에서 플랫폼을 선택하고, 필요하면 **서버 이름**을 지정한 다음 **등록 토큰**을 선택합니다. 접근 그룹은 이 양식에서 설정하지 않고 토큰에서 상속됩니다.

전체 등록 절차(Ansible 포함)는 [서버 등록하기](/use/servers/register/)를 참고하세요.

### 2단계: 생성된 명령으로 설치

워크스페이스에서 생성된 명령을 복사하여 서버에서 실행합니다. 워크스페이스는 선택한 플랫폼에 맞춰 명령을 자동 생성합니다.

**Linux / macOS**: 터미널에 붙여넣습니다.

```bash
# The command will look similar to this:
curl https://your-workspace.ap1.alpacon.io/api/servers/installers/YOUR_UNIQUE_ID/ | sudo -EH bash
```

**Windows**: 관리자 권한 PowerShell(관리자 권한으로 실행)에 붙여넣습니다. 생성된 명령은 GitHub Releases에서 에이전트를 내려받고 체크섬을 검증한 뒤 `alpamon.exe register`를 실행합니다. 동일한 수동 단계는 [Windows](#windows)를 참고하세요.

명령은 어느 경우든 다음을 수행합니다:
1. Alpamon 에이전트 설치
2. 워크스페이스에 서버 등록
3. 에이전트를 서비스로 시작

Linux와 macOS에서 `sudo -EH`는 환경 변수(예: 프록시 설정)를 유지하고 설치 과정의 `HOME`을 설정합니다.

### 3단계: 설치 확인

워크스페이스에서 서버 목록에 서버가 **온라인** 상태로 표시되는지 확인합니다. 이제 터미널을 통해 접근할 수 있습니다.

## 수동 설치 (고급)

대부분의 사용자에게는 워크스페이스에서 생성된 설치 명령 사용을 권장합니다 ([빠른 설치](#빠른-설치) 참조). 수동 설치 시 별도 등록이 필요합니다.

Linux 패키지는 [packagecloud.io](https://packagecloud.io/alpacax/alpamon)에서 호스팅됩니다. macOS는 Homebrew tap을 사용하고, Windows는 [GitHub Releases](https://github.com/alpacax/alpamon/releases)에 게시된 릴리스 아카이브를 사용합니다.

### Linux

#### 방법 1: 레포지토리 설치 (권장)

이 방법을 사용하면 시스템 패키지 관리자를 통한 자동 업데이트가 가능합니다.

##### 1단계: Alpacon에서 환경변수 가져오기

설치 전에 Alpacon 워크스페이스에서 등록 자격 증명을 가져와야 합니다.

**방법 A: Alpacon 웹 UI 사용**
1. Alpacon 워크스페이스에 로그인
2. **Servers** → **서버 등록**으로 이동
3. 새 서버 항목 생성
4. 설치 안내에서 환경변수 복사: `ALPACON_URL`, `PLUGIN_ID`, `PLUGIN_KEY`

**방법 B: Alpacon CLI 사용**
```bash
# CLI로 서버 생성 (대화형 프롬프트)
alpacon server create

# 생성 후 환경변수가 포함된 설치 안내가 표시됩니다
# ALPACON_URL, PLUGIN_ID, PLUGIN_KEY 값을 복사하세요
```

##### 2단계: 환경변수 설정

대상 서버에서 자격 증명을 export합니다.

```bash
export ALPACON_URL="https://your-workspace.ap1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"
```

설치 중에 이 변수들이 유지되도록 반드시 `export`로 내보내세요. `sudo -EH`의 `-EH` 플래그가 환경변수를 보존하고 설치 과정의 `HOME`을 설정합니다.

##### 3단계: Alpamon 설치

**DEB 기반 시스템 (Ubuntu/Debian):**

```bash
# 레포지토리 및 GPG 키 추가 (환경변수 보존)
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.deb.sh?any=true | sudo -EH bash

# Alpamon 설치 (환경변수를 사용하여 자동 등록)
sudo -EH apt-get install -y alpamon

# 서비스 시작 및 활성화
sudo systemctl start alpamon
sudo systemctl enable alpamon
```

**RPM 기반 시스템 (RHEL/Rocky/Alma/Fedora):**

```bash
# 레포지토리 추가 (환경변수 보존)
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.rpm.sh?any=true | sudo -EH bash

# Alpamon 설치 (환경변수를 사용하여 자동 등록)
sudo -EH yum install -y alpamon

# 서비스 시작 및 활성화
sudo systemctl start alpamon
sudo systemctl enable alpamon
```

**SUSE 기반 시스템 (openSUSE/SLES):**

```bash
# zypper에 저장소 추가 (alpamon 저장소가 이미 있으면 건너뜀)
sudo -EH zypper lr alpamon >/dev/null 2>&1 || \
  sudo -EH zypper --non-interactive addrepo -f \
  'https://packagecloud.io/alpacax/alpamon/rpm_any/rpm_any/$basearch' alpamon
sudo -EH zypper --non-interactive --gpg-auto-import-keys refresh alpamon

# Alpamon 설치 (자동 등록을 위해 환경 변수 사용)
sudo -EH zypper --non-interactive install alpamon

# 서비스 시작 및 활성화
sudo systemctl start alpamon
sudo systemctl enable alpamon
```

openSUSE와 SLES에서는 RPM 기반 시스템용 `script.rpm.sh` 명령을 쓰지 마세요. 이 명령이 만드는 저장소는 zypper가 쓰지 못합니다.

워크스페이스에 [sudo with MFA](/use/work-sessions/terminal/sudo-with-mfa/)가 활성화되어 있으면 설치 명령에 `alpamon-pam`을 추가하여 PAM 모듈도 함께 설치하세요. 예를 들어 `sudo -EH apt-get install -y alpamon alpamon-pam`(RHEL 계열은 `yum`, openSUSE와 SLES는 `zypper` 사용)입니다. openSUSE와 SLES에는 `alpamon-pam` 1.1.5 이상이 필요합니다([PAM 및 sudo 문제](/use/work-sessions/terminal/troubleshoot-sudo/#opensusesles에서-sudo가-실패하거나-root-비밀번호를-묻는-경우) 참고). 워크스페이스에서 생성된 명령은 이를 자동으로 추가합니다.

#### 방법 2: 직접 패키지 다운로드

특정 패키지 버전을 직접 다운로드하여 설치합니다. 이 방법도 자동 등록을 위해 환경변수가 필요합니다.

##### 1단계: 환경변수 가져오기 및 설정

방법 1과 동일한 단계로 `ALPACON_URL`, `PLUGIN_ID`, `PLUGIN_KEY`를 가져와서 export합니다.

```bash
export ALPACON_URL="https://your-workspace.ap1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"
```

##### 2단계: 다운로드 및 설치

**DEB 기반 시스템 (Ubuntu/Debian):**

```bash
# Download the package. Filenames follow alpamon_<version>_linux_<arch>.deb.
# Check the exact filename on the package page: https://packagecloud.io/alpacax/alpamon
wget "https://packagecloud.io/alpacax/alpamon/packages/ubuntu/focal/alpamon_<version>_linux_amd64.deb/download.deb" -O alpamon.deb

# 패키지 설치 (환경변수 보존)
sudo -EH dpkg -i alpamon.deb

# 누락된 종속성 설치
sudo -EH apt-get install -f -y

# 서비스 시작
sudo systemctl start alpamon
sudo systemctl enable alpamon
```

**RPM 기반 시스템 (RHEL/Rocky/Alma/Fedora):**

```bash
# Download the package. Filenames follow alpamon-<version>-1.linux.<arch>.rpm.
# Check the exact filename on the package page: https://packagecloud.io/alpacax/alpamon
wget "https://packagecloud.io/alpacax/alpamon/packages/el/8/alpamon-<version>-1.linux.x86_64.rpm/download.rpm" -O alpamon.rpm

# 패키지 설치 (환경변수 보존)
sudo -EH rpm -i alpamon.rpm

# 서비스 시작
sudo systemctl start alpamon
sudo systemctl enable alpamon
```

> **모든 패키지 찾아보기**: [packagecloud.io/alpacax/alpamon](https://packagecloud.io/alpacax/alpamon)에서 여러 OS 버전과 아키텍처별로 제공되는 모든 패키지를 확인하세요.

설치 중에 환경변수가 올바르게 설정되면 에이전트가 자동으로 등록됩니다. 그렇지 않으면 [수동 등록](#고급-수동-등록)을 진행하세요.

### macOS

Homebrew로 Alpamon을 설치한 뒤 `alpamon register`를 실행하면 설정 파일이 작성되고 launchd 서비스가 시작됩니다. 아래 `$(brew --prefix)` 형식은 Apple Silicon(`/opt/homebrew/bin`)과 Intel(`/usr/local/bin`) Mac 모두에서 동작합니다. Apple Silicon에서는 `sudo`가 Homebrew 바이너리를 찾지 못할 수 있으므로 전체 경로를 사용합니다.

```bash
brew tap alpacax/alpacon
brew install alpamon
sudo "$(brew --prefix)/bin/alpamon" register \
  --url https://your-workspace.ap1.alpacon.io \
  --token YOUR_REGISTRATION_TOKEN
```

`brew install`은 다시 실행해도 안전하지만, `alpamon register` 자체는 이미 등록된 호스트에서는 `config file already exists`로 실패합니다. 재등록하거나 복구하려면 서버에서 직접 `alpamon register --force`(또는 `alpamon unregister` 후 `alpamon register`)를 실행하세요. [등록 복구](/use/servers/troubleshooting/#재등록-및-복구)를 참고하세요.

### Windows

**관리자 권한 PowerShell**(관리자 권한으로 실행)을 열고 아래 두 방법 중 하나를 선택하세요. 두 방법 모두 `alpamon.exe register`가 에이전트를 `C:\Program Files\alpamon\`에 설치하고, 부팅 시 자동으로 시작되는 Windows 서비스로 등록한 뒤 서비스를 시작합니다. `install.ps1` 스크립트는 다시 실행해도 안전하지만, `alpamon.exe register` 자체는 이미 등록된 호스트에서는 `config file already exists`로 실패합니다. 재등록하거나 복구하려면 Websh가 아닌 서버에서 직접 `alpamon.exe register --force`(또는 `alpamon.exe unregister` 후 `alpamon.exe register`)를 실행하세요. [등록 복구](/use/servers/troubleshooting/#재등록-및-복구)를 참고하세요.

#### 방법 1: 수동 설치

1. [GitHub Releases](https://github.com/alpacax/alpamon/releases)에서 `alpamon-X.Y.Z-windows-amd64.zip`을 다운로드합니다. 바이너리가 서명되어 있지 않아 Windows가 SmartScreen으로 차단할 수 있으므로, 압축을 풀기 **전에** ZIP 파일의 차단을 해제하세요: `Unblock-File .\alpamon-X.Y.Z-windows-amd64.zip`. 그런 다음 압축을 풉니다.
2. 압축을 푼 폴더에서 관리자 권한 PowerShell을 통해 실행:

```powershell
.\alpamon.exe register `
    --url https://your-workspace.ap1.alpacon.io `
    --token YOUR_REGISTRATION_TOKEN
```

#### 방법 2: `install.ps1` 자동 설치

cloud-init, EC2 UserData, Packer, Azure Custom Script Extension에 권장됩니다. 스크립트는 릴리스 아카이브를 다운로드하고, 릴리스와 함께 게시된 체크섬으로 다운로드 무결성을 검증한 뒤 압축을 풀고 `alpamon register`를 실행합니다.

**파일 다운로드 후 실행** (권장: 설치 스크립트가 디스크에 남아 감사가 가능합니다):

```powershell
$env:ALPAMON_URL   = "https://your-workspace.ap1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_REGISTRATION_TOKEN"
$installer = Join-Path $env:TEMP 'alpamon-install.ps1'
Invoke-WebRequest -UseBasicParsing `
    -Uri 'https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1' `
    -OutFile $installer
& powershell -ExecutionPolicy Bypass -File $installer
```

**파이프 `iex` 형식** (명령이 짧지만 나중에 검토할 스크립트 파일은 남지 않습니다):

```powershell
$env:ALPAMON_URL   = "https://your-workspace.ap1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_REGISTRATION_TOKEN"
iwr https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1 -UseB | iex
```

## 고급: 수동 등록

Alpamon을 수동으로 설치한 경우(워크스페이스에서 생성된 설치 명령을 사용하지 않고)에는 별도로 등록할 수 있습니다:

### 등록 정보 받기

1. Alpacon 워크스페이스에 로그인
2. **Servers** → **서버 등록**으로 이동한 뒤 **토큰으로 등록** 선택
3. **서버 등록 토큰** 필드에서 **새 토큰 만들기**를 클릭하고 표시되는 키를 복사합니다. 키는 한 번만 표시되므로, 기존 [서버 등록 토큰](/use/servers/register/tokens/)을 쓰려면 만들 때 저장해 둔 키를 사용하세요.

### 서버 등록

서버에서 등록 명령 실행:

```bash
sudo alpamon register \
  --url https://your-workspace.ap1.alpacon.io \
  --token YOUR_REGISTRATION_TOKEN \
  --name "production-web-01" \
  --tag env=prod --tag role=web
```

옵션:
- `--url`: Alpacon 서버 URL (필수)
- `--token`: [서버 등록 토큰](/use/servers/register/tokens/) 키 (필수)
- `--name`: 서버 이름 (선택사항, 기본값: 호스트네임)
- `--platform`: 플랫폼 타입 `debian`, `rhel`, `darwin`, `windows` (선택사항, 자동 감지)
- `--ssl-verify`: SSL 인증서 검증 활성화 (기본값: true)
- `--ca-cert`: CA 인증서 파일 경로 (선택사항)
- `--tag`: `key=value` 형식의 서버 태그 (선택사항, 반복 지정 가능)
- `--no-cloud-probe`: 클라우드 호스트에서 클라우드 제공자 메타데이터 자동 감지 건너뛰기 (선택사항)
- `--force`: 막힌 서버 복구. 새로 등록한 뒤, 새 등록이 커밋되면 이전 등록을 회수합니다(이전 등록은 새 등록이 성공할 때까지 유지). alpamon v2.3.0 이상 필요.
- `--no-rollback`: 등록이 실패해도 부분 상태를 정리하지 않고 그대로 둡니다(디버그 전용, 일반 사용 비권장). alpamon v2.3.0 이상 필요.

### 등록 확인

플랫폼에 맞는 명령으로 에이전트 상태를 확인합니다.

**Linux**

```bash
sudo systemctl status alpamon
sudo journalctl -u alpamon -f
```

**macOS**

```bash
sudo launchctl print system/com.alpacax.alpamon
tail -f /var/log/alpamon/alpamon.log
```

**Windows**

```powershell
sc.exe query alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Wait -Tail 50
```

워크스페이스에서:
1. **Servers** 페이지로 이동
2. 서버가 "Connected"로 표시되어야 함
3. 서버를 클릭하여 터미널에 접근

## 관련 작업

- <span id="구성" /><span id="구성-파일" /><span id="환경-변수" /><span id="프록시-구성" /><span id="성능-튜닝" />[Alpamon 구성](/reference/agent-configuration/): 경로, 등록 환경 변수, 프록시 설정 및 성능 관련 기본값
- <span id="에이전트-업그레이드" />[서버 관리](/use/servers/manage/#에이전트-카드): 에이전트 업그레이드
- <span id="제거" /><span id="linux-1" /><span id="macos-1" /><span id="windows-1" />[서버 제거](/use/servers/remove/): Linux, macOS, Windows에서 제거
- <span id="문제-해결" /><span id="에이전트가-시작되지-않음" /><span id="등록-실패" />[에이전트 문제 해결](/use/servers/troubleshooting/): 시작 및 등록 실패 해결
- <span id="연결-문제" />[연결 문제 해결](/use/work-sessions/troubleshoot-connections/): 네트워크 연결 점검

## 다음 단계

설치를 마쳤다면 다음을 진행하세요.

1. **[접근 제어 구성](/learn/best-practices/permission-management/)** - 역할 및 권한 설정
2. **[Websh를 통한 연결](/use/work-sessions/terminal/)** - 브라우저를 통해 서버에 접근
3. **[활동 검토](/use/audit/)** - 세션·명령·승인 결정 감사
4. **[CI/CD와 통합](/integrate/)** - 배포 자동화

## 도움이 필요하신가요?

- **[문제 해결 가이드](/use/work-sessions/troubleshoot-connections/)** 확인
- **[FAQ](/learn/faq/)** 방문
- **[Discord 커뮤니티](https://discord.gg/wadWh8VsYB)** 참여
- 이메일 지원: support@alpacax.com

Source: https://docs.alpacax.com/ko/use/servers/register/install/