macOS

지원 환경: macOS 10.15 이상 (Catalina 또는 이후 버전), Apple Silicon 및 Intel.

설치

빠른 설치
소스에서 빌드

터미널을 엽니다.
설치 스크립트를 실행합니다:
Terminal window
```
curl -sSL https://proxy.sotatek.works/releases/download/latest/install.sh | bash
```
스크립트는 해당 아키텍처에 맞는 바이너리를 다운로드하고 SHA256 체크섬을 검증한 후 /usr/local/bin/sotatek-proxy (또는 /usr/local/bin에 쓰기 권한이 없는 경우 ~/.local/bin/sotatek-proxy)에 배치합니다. 기본 설정 파일을 생성하고, 로그인 시 자동 시작되는 launchd 사용자 에이전트를 등록합니다.
데몬이 정상적으로 실행 중인지 확인합니다:
Terminal window
```
sotatek-proxy status
curl http://127.0.0.1:3817/_proxy/healthz
```

저장소를 클론합니다:

git clone https://github.com/sotatek-dev/sotatek-proxy.git
cd sotatek-proxy

빌드 후 설치합니다:
Terminal window
```
bash scripts/install-from-source.sh
```
스크립트는 현재 플랫폼(Apple Silicon 또는 Intel)을 감지하여 make build-darwin-arm64 / make build-darwin-amd64를 실행하고, 바이너리를 /usr/local/bin/sotatek-proxy (또는 /usr/local/bin에 쓰기 권한이 없는 경우 ~/.local/bin/sotatek-proxy)에 복사하며, 기본 설정 파일을 생성하고 launchd 사용자 에이전트를 등록합니다.

선택적 플래그:

플래그 설명
--no-service 바이너리만 설치 — launchd 에이전트 등록 생략
--prefix DIR 설치 디렉토리 재정의
데몬이 정상적으로 실행 중인지 확인합니다:
Terminal window
```
sotatek-proxy status
curl http://127.0.0.1:3817/_proxy/healthz
```

플래그	설명
`--no-service`	바이너리만 설치 — launchd 에이전트 등록 생략
`--prefix DIR`	설치 디렉토리 재정의

파일 위치

항목	경로
바이너리	`/usr/local/bin/sotatek-proxy` (또는 `~/.local/bin/sotatek-proxy`)
설정	`~/Library/Application Support/sotatek-proxy/config.yaml`
로그	`~/Library/Logs/sotatek-proxy/sotatek-proxy.log`
서비스	`~/Library/LaunchAgents/com.sotatek.proxy.plist`

서비스 명령어

sotatek-proxy status      # 실행 중 / 정지됨
sotatek-proxy start       # 지금 시작
sotatek-proxy stop        # 지금 정지
sotatek-proxy logs        # 마지막 100줄 출력
sotatek-proxy uninstall   # launchd 에이전트 제거

문제 해결

sotatek-proxy status가 command not found를 반환하면, 바이너리가 (/usr/local/bin에 쓸 수 없어) ~/.local/bin에 설치되었고 해당 디렉터리가 PATH에 없는 것입니다. macOS는 기본적으로 zsh를 사용하므로 path는 ~/.zshrc에 들어갑니다.

올바른 셸 rc 파일에 추가한 후 다시 로드하세요:

case "$(basename "${SHELL:-zsh}")" in
  bash) RC="$HOME/.bash_profile" ;;
  *)    RC="$HOME/.zshrc" ;;
esac
LINE='export PATH="$HOME/.local/bin:$PATH"'
grep -qxF "$LINE" "$RC" 2>/dev/null || echo "$LINE" >> "$RC"
source "$RC"

또는 현재 셸에서만 임시로 적용 (새 세션 불필요):

export PATH="$HOME/.local/bin:$PATH"
sotatek-proxy status

다른 프로세스가 3817 포트를 사용 중입니다. 포트를 해제하거나 설정을 변경하세요:

lsof -i :3817            # 사용 중인 프로세스 찾기
sotatek-proxy stop && sotatek-proxy start

또는 config.yaml에서 port: 3818로 설정하고 재시작하세요.

sotatek-proxy logs
launchctl print gui/$UID/com.sotatek.proxy
sotatek-proxy daemon     # 디버깅을 위한 포그라운드 실행

에이전트가 로드되어 있는지 확인합니다:

launchctl list | grep com.sotatek.proxy
sotatek-proxy daemon     # 포그라운드 동작 확인

제거

sotatek-proxy uninstall
rm /usr/local/bin/sotatek-proxy   # 또는 ~/.local/bin/sotatek-proxy
rm -rf ~/Library/Application\ Support/sotatek-proxy
rm -rf ~/Library/Logs/sotatek-proxy