설치

snowpea는 런타임 두 개가 필요합니다: Python 3.11+(uv가 관리)와 Node 20+. 없으면 설치 스크립트가 둘 다 마련해 줍니다. 터미널 UI는 Python wheel 안에 미리 번들되어 있어서, 내 컴퓨터에서 npm install을 돌릴 일은 없습니다.

한 줄 설치

macOS, Linux, WSL2

curl -fsSL https://raw.githubusercontent.com/Wafour-Developer/snowpea-agent/main/installer/install.sh | sh

Windows (PowerShell)

iwr https://raw.githubusercontent.com/Wafour-Developer/snowpea-agent/main/installer/install.ps1 | iex

그다음 확인합니다.

snowpea --version

이 스크립트는 멱등적입니다 — 다시 돌리면 그 자리에서 업그레이드됩니다. 공식 설치 프로그램으로 uv를 설치하고, node --version이 20 이상을 보고하는지 확인하고, snowpea 명령을 uv tool로 설치한 뒤, ~/.local/bin이 아직 PATH에 없으면 셸 프로필에 추가합니다. Windows에서는 데이터 디렉터리가 ~/.snowpea 대신 %LOCALAPPDATA%\snowpea입니다.

아무것도 건드리지 않고 무엇을 할지만 보려면 먼저 내려받아 --dry-run을 붙이세요.

curl -fsSL https://raw.githubusercontent.com/Wafour-Developer/snowpea-agent/main/installer/install.sh -o install.sh
sh install.sh --dry-run

수동 설치

스크립트를 셸로 곧장 흘려보내고 싶지 않거나, 한 줄 설치가 어느 단계에서 실패해서 직접 그 단계를 하고 싶다면:

curl -LsSf https://astral.sh/uv/install.sh | sh     # uv, if missing
uv tool install snowpea-agent
snowpea --version

터미널 UI를 쓰려면 Node 20+가 PATH에 있어야 합니다. 헤드리스 실행(snowpea -c)과 모든 snowpea <subcommand>는 Node 없이도 동작합니다. Node가 필요한 것은 TUI뿐입니다.

설치 소스 재정의

설치 스크립트는 설치 소스를 바꿀 수 있습니다. CI와 오프라인 설치가 쓰는 경로입니다.

sh install.sh --from-checkout
SNOWPEA_WHEEL_URL=./snowpea_agent-0.1.0-py3-none-any.whl sh install.sh
SNOWPEA_INSTALL_SOURCE=git+https://github.com/Wafour-Developer/snowpea-agent sh install.sh

SNOWPEA_BIN_DIR은 snowpea 실행 파일이 놓일 위치를 바꾸고, --from-checkout은 스크립트 자신이 들어 있는 체크아웃을 설치합니다.

체크아웃에서 직접

git clone https://github.com/Wafour-Developer/snowpea-agent.git
cd snowpea-agent
uv sync
npm ci
npm run build
uv run snowpea --version

npm run build는 tui/dist/snowpea-tui.js를 만들고, snowpea는 번들된 패키지보다 이 파일을 먼저 찾습니다. UI를 작업하는 동안은 SNOWPEA_TUI_ENTRY가 직접 만든 엔트리 파일을 가리키게 해서 번들을 아예 건너뛸 수 있습니다.

업데이트

snowpea는 하루에 한 번 백그라운드에서 새 릴리스를 확인하고, 그 답을 $SNOWPEA_HOME/update-check.json에 캐시합니다. 사용자가 승인하지 않으면 아무것도 설치하지 않습니다.

터미널 UI에서. 업데이트가 있으면 화면 위쪽에 배너가 뜹니다.

⬆ Update available v0.1.2 (current v0.1.1) — press U or type /update

U를 누르거나 /update를 입력한 뒤 y로 답하세요. 업그레이드는 백그라운드에서 돌고, 배너가 진행 상황을 알리고, 끝나면 snowpea가 새 버전으로 스스로 다시 시작합니다. 진행 중인 턴은 절대 중단되지 않습니다.

명령줄에서.

snowpea update --check
snowpea update

--check는 현재 버전과 최신 버전만 알려주고 아무것도 설치하지 않습니다. 그냥 snowpea update를 쓰면 업그레이드를 실행하고 데몬을 멈춘 뒤 snowpea를 다시 실행하라고 알려줍니다. snowpea --version도 대기 중인 업데이트를 함께 알려주는데, 캐시만 읽으므로 네트워크를 기다리지 않습니다.

업그레이드 출력은 $SNOWPEA_HOME/logs/update.log에 쌓입니다. 기본 명령은 uv tool install --force --reinstall이고, uv가 PATH에 없으면 설치 프로그램이 $SNOWPEA_HOME/install.json에 기록해 둔 방식을 씁니다. 그것도 없으면 짐작하는 대신 직접 실행할 명령을 인쇄합니다.

$SNOWPEA_HOME/settings.json의 설정 두 개가 이 동작을 정합니다.

{ "updates": { "check": true, "channel": "auto" } }

check: false는 매일 하는 백그라운드 확인만 끄고, /update와 snowpea update는 그대로 동작합니다. channel은 auto(패키지가 PyPI에 있으면 PyPI, 없으면 저장소의 git 태그), pypi, git 중 하나입니다.

직접 업그레이드하려면:

uv tool upgrade snowpea-agent
snowpea daemon stop
snowpea --version

직접 업그레이드한 뒤에는 데몬을 멈추세요. 돌고 있는 데몬은 옛 코드를 메모리에 그대로 들고 있고, 다음에 붙는 클라이언트는 이미 설치된 것과 더 이상 맞지 않는 프로토콜 버전으로 협상하게 됩니다.

데스크톱 앱

현재 운영체제와 CPU에 맞는 데스크톱 앱을 설치하고 실행하려면 다음 명령을 사용하세요.

snowpea desktop

이미 설치되어 있으면 앱만 실행합니다. 설치된 버전과 최신 버전을 비교하려면 snowpea desktop --check, 업그레이드하거나 다시 설치하려면 snowpea desktop --reinstall, 실행하지 않고 설치만 하려면 snowpea desktop --install-only를 사용하세요. 스크립트에서는 --yes를 추가하면 대화형 확인 없이 다운로드를 승인합니다.

제거

snowpea daemon stop
uv tool uninstall snowpea-agent

여기까지는 데이터를 남깁니다. 데이터까지 지우려면 $SNOWPEA_HOME(~/.snowpea, Windows에서는 %LOCALAPPDATA%\snowpea)을 삭제하세요. 데몬을 서비스로 등록해 두었다면 먼저 등록을 해제합니다.

snowpea service uninstall

뭔가 잘못됐을 때

설치 직후 snowpea: command not found. 이 셸에서는 ~/.local/bin이 아직 PATH에 없습니다. 새 터미널을 열거나 셸 프로필을 다시 불러오세요. 설치 스크립트는 그 줄을 프로필에 추가할 뿐, 지금 서 있는 셸 자체를 바꾸지는 못합니다.

Node가 없거나 너무 낮습니다. TUI가 뜨지 않습니다. 패키지 매니저나 nodejs.org에서 Node 20+를 설치한 뒤 snowpea를 다시 실행하세요. 그동안 나머지는 계속 동작합니다.

snowpea -c "hello" --json

데몬이 시작되지 않습니다. $SNOWPEA_HOME/logs/daemon.log를 보고, 오래된 프로세스가 기록된 포트를 붙잡고 있지 않은지 확인하세요.

snowpea daemon status
snowpea daemon stop
snowpea daemon start

daemon status는 $SNOWPEA_HOME/daemon.json을 읽고 그 pid가 살아 있는지 확인합니다. pid가 죽은 오래된 파일은 지워도 안전합니다.

회사 프록시 또는 오프라인 머신. uv tool install은 PyPI가 필요합니다. 설치 스크립트를 돌리기 전에 HTTPS_PROXY를 설정하거나, 직접 들고 온 wheel로 설치하세요: uv tool install ./snowpea_agent-0.1.0-py3-none-any.whl.

다음

설정 — 벤더를 고르고 키를 마련합니다.