시작하기

설치, 모델 설정, 첫 세션 실행 절차를 설명합니다.

이 문서에서 다루는 내용

• 설치하기
• 모델 연결하기
• 첫 작업 맡기기
• 다음 문서 고르기

1. 설치하기

snowpea는 macOS, Linux, WSL2, Windows PowerShell에서 설치할 수 있습니다. Python 3.11 이상은 설치 스크립트가 uv로 처리하고, 터미널 UI(TUI)를 실행하려면 Node 20 이상이 필요합니다. LLM 벤더는 v0.1 기준 열한 곳 중 하나를 사용합니다.

데스크톱 앱 설치 파일은 https://agent.snowpea.ai/download에서 운영체제별로 받을 수 있습니다.

macOS, Linux, WSL2

1. 터미널에서 설치 스크립트를 실행합니다.

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

   snowpea 명령이 uv tool로 설치됩니다.

Windows PowerShell

1. PowerShell에서 설치 스크립트를 실행합니다.

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

   snowpea 명령이 설치됩니다.

설치 스크립트 동작

설치 스크립트는 멱등합니다. 다시 실행하면 두 번째 사본을 설치하지 않고 현재 설치를 업그레이드합니다.

동작	결과
uv 확인	없으면 공식 인스톨러로 설치합니다.
node --version 확인	20 이상인지 확인합니다.
snowpea 설치	snowpea 명령을 uv tool로 설치합니다.
PATH 확인	~/.local/bin이 PATH에 없으면 셸 프로필에 추가합니다.

설치 전 확인

1. 설치 스크립트를 파일로 내려받습니다.

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

   install.sh 파일이 생성됩니다.

2. --dry-run으로 실행합니다.

   sh install.sh --dry-run

   변경 없이 실행 예정 작업이 표시됩니다.

수동 설치

1. uv가 없을 때 공식 설치 스크립트를 실행합니다.

   curl -LsSf https://astral.sh/uv/install.sh | sh     # uv가 없을 때만

   uv가 설치됩니다.

2. snowpea-agent를 uv tool로 설치합니다.

   uv tool install snowpea-agent

   snowpea 명령이 설치됩니다.

설치 확인

1. 버전 명령을 실행합니다.

   snowpea --version

   설치된 snowpea 버전이 출력됩니다.

snowpea: command not found 가 나오면

~/.local/bin이 현재 셸의 PATH에 없는 상태입니다. 인스톨러는 프로필에 경로를 추가하지만 이미 열려 있는 셸의 환경은 바꾸지 않습니다. 새 터미널을 열거나 프로필을 다시 읽으십시오.

2. 모델 연결하기

모델 설정은 snowpea setup 명령으로 저장합니다. 설정이 없을 때 snowpea를 실행하면 첫 실행에서 설정 마법사가 열립니다.

The first-run setup wizard on the vendor screen: the eleven vendors, the star on the default, and the auth choices.

설정 명령

명령	동작	결과
snowpea setup	LLM 모델만 선택하고 나머지는 기본값을 사용합니다.	빠른 설정이 저장됩니다.
snowpea setup --full	다섯 화면을 순서대로 표시합니다.	모든 설정 항목을 확인할 수 있습니다.
snowpea setup --blank	질문 없이 기본값을 씁니다.	CI용 기본 설정이 저장됩니다.

--full은 다섯 화면과 요약 한 장으로 구성됩니다. 모든 화면에는 Skip — keep defaults가 있고, 모든 화면에 대응하는 커맨드라인 플래그가 있습니다.

화면	무엇을 고르나	플래그
Providers	LLM 벤더, 키, 모델	--vendor, --key, --model, --base-url
Search	웹 검색 제공자 하나	--search-provider
Browser	브라우저 제공자 하나	--browser-provider
Tools	켜 둘 툴 카테고리	--tools
Gateway	Telegram / Discord / Slack	--gateway, --token, --user-id

목록은 키가 필요 없는 무료 → 키가 필요한 무료나 자체 호스팅 → 유료 순서로 정렬됩니다. 각 목록의 기본값에는 별표가 붙습니다. 기본 설정에서 비용이 드는 항목은 LLM 벤더뿐이며, 웹 검색과 브라우저는 키 없이 동작합니다.

벤더 고르기

벤더는 모델 제공자를 뜻합니다. v0.1 기준으로 열한 곳을 사용할 수 있습니다.

벤더 id	이름	어댑터	인증
anthropic	Anthropic	네이티브 Messages API	API 키
openai	OpenAI	OpenAI 호환	API 키, 디바이스 코드 로그인
openrouter	OpenRouter	OpenAI 호환	API 키, OAuth PKCE 로그인
gemini	Google Gemini	네이티브	API 키, Google OAuth, 액세스 토큰
xai	xAI Grok	OpenAI 호환	API 키
glm	Zhipu GLM	OpenAI 호환	API 키
minimax	MiniMax	OpenAI 호환	API 키
kimi	Moonshot Kimi	OpenAI 호환	API 키
deepseek	DeepSeek	OpenAI 호환	API 키
qwen	Qwen	OpenAI 호환	API 키
local	로컬 (vLLM · Ollama · LM Studio)	OpenAI 호환	base URL, 키는 선택

이미 계정이 있는 벤더를 선택합니다. 어댑터가 네이티브인지 OpenAI 호환인지는 snowpea 사용 방식에 영향을 주지 않습니다. local을 선택해 Ollama나 vLLM을 붙일 때는 툴 호출을 지원하는 모델을 사용해야 합니다.

비대화형 벤더 설정

1. 벤더와 API 키를 플래그로 전달합니다.

   snowpea setup --vendor deepseek --key sk-your-key-here
   snowpea setup --vendor anthropic --key sk-ant-... --model claude-sonnet-4-5

   지정한 벤더 설정이 저장됩니다.

OPENAI_API_KEY나 ANTHROPIC_API_KEY가 환경변수로 있으면 마법사가 먼저 제안합니다. 같은 키를 다시 붙여 넣을 필요가 없습니다.

브라우저 로그인

1. OpenAI 디바이스 코드 로그인을 실행합니다.

   snowpea provider login openai        # 디바이스 코드: 코드가 뜨고, 브라우저에서 승인

   브라우저 승인 후 OpenAI 인증이 저장됩니다.

2. OpenRouter OAuth PKCE 로그인을 실행합니다.

   snowpea provider login openrouter    # OAuth PKCE: 로컬 콜백이 코드를 받습니다

   로컬 콜백이 코드를 받은 뒤 OpenRouter 인증이 저장됩니다.

그 밖의 벤더는 login_unsupported로 답하고 대신 실행할 --vendor/--key 명령을 알려 줍니다.

설정 확인

1. 설정된 제공자 목록을 출력합니다.

   snowpea provider list

   현재 설정된 벤더와 인증 상태가 표시됩니다.

검색과 브라우저

기본 검색 제공자는 ddgs이며 계정과 키가 필요 없습니다. 브라우저 기본값은 local_chromium이며, Playwright가 로컬 컴퓨터에서 헤드리스 Chromium을 실행합니다. 첫 실행에서 브라우저 바이너리 다운로드 여부를 물을 수 있습니다.

3. 첫 작업 맡기기

세션은 작업할 프로젝트 디렉터리에서 시작합니다. 세션은 데몬(snowpea core)이 프로젝트별 작업 상태를 관리하는 실행 단위입니다.

1. 작업할 프로젝트 디렉터리로 이동합니다.

   cd ~/projects/my-app

   현재 디렉터리가 프로젝트 루트로 바뀝니다.

2. 인자 없이 snowpea를 실행합니다.

   snowpea

   터미널 UI(TUI)가 열립니다.

The TUI launch screen: banner, version line, the working directory, the active vendor and model, and the mode indicator.

TUI는 먼저 터미널 폭에 맞춘 워드마크를 출력합니다. 이어서 버전, 벤더/모델, 작업 디렉터리, 모드를 표시합니다. 데몬(snowpea core)이 같은 디렉터리에 열린 세션을 가지고 있으면 마지막 세션 한 줄이 추가되고, 빈 입력에서 R을 누르면 그 세션이 현재 창으로 이어집니다.

배너는 한 번 출력됩니다. 다른 출력과 같이 스크롤됩니다.

첫 프롬프트

1. 입력 줄에 프롬프트를 입력합니다.

   > README.md 를 읽고 이 프로젝트가 뭘 하는 건지 세 문장으로 설명해줘

   에이전트가 README.md를 읽고 세 문장으로 설명합니다.

A live session mid-answer: user prompt, streaming assistant text, a tool call with its arguments collapsed, and the status bar showing tokens and elapsed time.

입력 위의 한 줄은 현재 동작을 표시합니다. ✢ Pondering… (12s · ↓ 3.7k tokens)는 모델이 생각 중임을 뜻하고, ✳ Running shell: npm test…는 툴이 실행 중임을 뜻합니다. 시계와 토큰 수는 이번 턴의 값이며, 세션 전체 합계는 상태 줄에 있습니다.

Esc를 누르면 현재 턴을 중단합니다. 툴 호출이 여러 번 연달아 끝나면 다음 형식으로 접힙니다.

⏺ Ran 2 shell commands (34 lines)
⏺ Read 3 files (128 lines)

실패한 호출은 출력과 함께 개별 카드로 남습니다. Ctrl+O를 누르면 가장 최근 툴 호출이나 diff가 펼쳐집니다.

기본 모드는 accept

상태 줄 오른쪽의 Mode: ACCEPT가 기본값입니다. 파일 읽기와 파일 수정은 묻지 않고 실행되며, 셸 명령, 네트워크 호출, 메시지 전송은 먼저 승인 요청을 표시합니다. Shift+Tab은 accept → auto → plan 순서로 모드를 전환합니다.

자세한 경계는 모드에 있습니다. 승인 메뉴에서 커서는 Yes에 있으며, Enter는 예를 선택합니다. y, a(이 세션 동안 다시 묻지 않음), p(이 프로젝트에 허용 규칙 추가), n을 바로 입력할 수 있습니다.

4. 다음 문서 고르기

• 사용 설명서 — 화면별 사용법.
• 모드 — 권한 태그, 모드 행렬, 허용 목록(allowlist).
• 명령 — 슬래시 명령과 CLI 서브커맨드 전체 목록.
• FAQ · 문제 해결 — 오류와 복구 절차.
• 데스크톱 앱 — 같은 데몬을 창으로 사용하는 방법.

다음 단계

사용 설명서 보기화면별 사용법을 확인합니다.→모드 이해하기승인과 권한 범위를 정합니다.→문제 해결하기증상별 해결 방법을 확인합니다.→