작동 방식

snowpea의 로컬 데몬, 클라이언트 연결 방식, 프로토콜 흐름, 저장 위치를 설명합니다.

이 문서에서 다루는 내용

전체 흐름
데몬이 소유하는 상태
클라이언트 연결
클라이언트 선택
저장 위치

전체 흐름

데몬(snowpea core)은 Python으로 만든 로컬 프로세스이며 상태를 가진 모든 데이터를 소유합니다. 터미널 UI(TUI), 데스크톱 앱, 직접 만든 클라이언트는 데몬에 붙는 클라이언트입니다. 클라이언트는 문서화된 WebSocket JSON-RPC 프로토콜로 데몬과 통신합니다.

text

        ┌──────────────┐   ┌──────────────────┐   ┌────────────────┐
        │  터미널 UI   │   │  데스크톱 앱     │   │  직접 만든 것  │
        └──────┬───────┘   └────────┬─────────┘   └───────┬────────┘
               │                    │                     │
               └──────── ws://127.0.0.1:<port>/ws ────────┘
                                    │
                          ┌─────────┴──────────┐
                          │   snowpea 데몬     │
                          │  세션 · 툴 · 권한  │
                          │  메모리 · 스케줄   │
                          └─────────┬──────────┘
                                    │
                     LLM 벤더 · 파일 · 셸 · 웹

데몬이 소유하는 상태

데몬은 세션, 툴, 권한, 메모리, 스케줄, 메신저 연결의 기준 상태를 보관합니다. 클라이언트는 이 상태를 따로 저장하지 않습니다.

상태	설명
세션	대화와 그 안에서 오간 모든 이벤트
툴	파일 읽기·수정, 셸, 웹 검색, 브라우저처럼 에이전트가 실제로 수행하는 작업
권한	묻지 않고 실행할 툴과 실행 전에 승인을 요청할 툴의 구분
메모리	세션을 넘어 유지되는 기억. 이름을 붙인 에이전트는 별도 영역을 가집니다
스케줄	"매일 9시" 같은 예약 작업. 별도 cron 데몬이 아니라 데몬 안에서 실행됩니다
메신저 연결	Telegram·Discord·Slack 바인딩

데몬이 스케줄을 소유하므로 터미널을 닫아도 예약 작업은 계속 실행됩니다. 터미널 UI와 데스크톱 앱은 같은 세션을 표시하므로 같은 대화를 두 위치에서 이어 사용할 수 있습니다.

데몬은 첫 클라이언트가 연결될 때 시작합니다. 열린 세션, 켜 둔 예약 작업, 메신저 연결, 이름 붙인 에이전트가 모두 없으면 종료됩니다.

데몬 상태를 확인하려면 다음 명령을 실행합니다.
bash
```
snowpea daemon status
```
현재 데몬을 유지하는 세션, 작업, 연결, 에이전트가 표시됩니다.

클라이언트 연결

데몬은 시작할 때 루프백 전용 포트를 선택합니다. 데몬은 연결 정보를 $SNOWPEA_HOME/daemon.json에 {port, pid, token, startedAt, protocolVersion}로 저장합니다. 클라이언트는 먼저 이 파일을 읽습니다.

표면	주소	용도
WebSocket	`ws://127.0.0.1:<port>/ws`	JSON-RPC 2.0, 양방향
HTTP `GET`	`/health`	살아 있는지 확인
HTTP `GET`	`/protocol.json`	스키마를 JSON 으로
HTTP `GET`	`/version`	서버와 프로토콜 버전

데몬은 루프백 전용이므로 네트워크에 열려 있지 않습니다. 다른 호스트의 코드를 다룰 때는 포트를 여는 대신 백엔드 (docker, ssh)를 사용합니다.

연결된 클라이언트는 즉시 system.hello를 호출합니다. 파라미터는 $SNOWPEA_HOME/token에서 읽은 토큰, 클라이언트 버전, 클라이언트가 빌드된 프로토콜 버전입니다. 그 전에 다른 메서드를 호출하면 unauthorized로 실패하고, 메이저 버전이 맞지 않으면 protocol_incompatible로 거절됩니다.

system.hello 이후에는 양방향 통신이 시작됩니다. 클라이언트는 session.*, turn.*, approval.*, schedule.*, memory.* 같은 메서드를 호출합니다. 데몬은 message.delta, tool.call, diff, turn.done 같은 이벤트를 전송합니다.

프로토콜의 정확한 스키마는 프로토콜 레퍼런스에 있습니다. 프로토콜 개요는 레퍼런스와 TypeScript 바인딩이 코어 소스에서 함께 생성되는 방식을 설명합니다. 둘이 어긋나면 CI가 빌드를 깹니다.

클라이언트 선택

클라이언트	사용 방식
터미널 UI(TUI)	`snowpea`를 실행하면 데몬이 필요할 때 시작되고 UI가 연결됩니다
데스크톱 앱 (snowpea desktop)	같은 데몬에 연결되는 별도 창입니다. 설치해도 세션은 이동하지 않고 같은 세션을 표시합니다
헤드리스 CLI	`snowpea -c "..."`는 UI 없이 한 턴만 실행하고 종료 코드를 남깁니다. `--json`을 붙이면 이벤트가 JSON Lines로 출력됩니다
직접 만든 클라이언트	TypeScript SDK가 같은 프로토콜을 사용합니다

헤드리스 CLI에서 이벤트를 JSON Lines로 확인하려면 다음 명령을 실행합니다.
bash
```
snowpea -c "README.md 를 요약해줘" --json
```
한 턴이 실행되고 프로토콜 이벤트가 JSON Lines로 출력됩니다.

저장 위치 확인하기

snowpea 데이터는 로컬 컴퓨터에 저장됩니다.

경로	무엇
`$SNOWPEA_HOME` (기본값 `~/.snowpea`)	전역으로 쓰는 모든 것
`$SNOWPEA_HOME/settings.json`	벤더, 검색·브라우저 선택, 툴 분류, 타임아웃
`$SNOWPEA_HOME/credentials.json`	봇 토큰과 비밀값. 권한 `0600`
`$SNOWPEA_HOME/daemon.json`	포트, pid, 토큰, 시작 시각, 프로토콜 버전
`$SNOWPEA_HOME/state.db`	세션·이벤트·메모리·잡·팀 태스크·이름 붙인 에이전트
`$SNOWPEA_HOME/logs/`	`daemon.log`, `approvals.jsonl`
`$SNOWPEA_HOME/plugins/`, `skills/`, `agents/`, `commands/`	설치했거나 직접 쓴 확장
`<프로젝트>/.snowpea/settings.json`	이 저장소의 기본 모드, 허용 목록, 백엔드
`<프로젝트>/.snowpea/{skills,agents,commands}/`	프로젝트 전용 확장
`<프로젝트>/.claude/{skills,agents,commands}/`	Claude Code 호환으로 읽는 자리

SNOWPEA_HOME은 모든 위치에서 적용됩니다.

완전히 분리된 두 번째 설치를 사용하려면 다음 명령을 실행합니다.
bash
```
SNOWPEA_HOME=/tmp/snowpea-scratch snowpea daemon status
```
/tmp/snowpea-scratch를 SNOWPEA_HOME으로 사용하는 별도 상태에서 데몬 상태가 표시됩니다.

LLM 벤더에게 보내는 프롬프트만 컴퓨터 밖으로 나갑니다. snowpea가 자체적으로 접속하는 첫 번째 당사자 서비스는 registry.snowpea.ai이며, 스킬을 검색하거나 설치할 때만 사용됩니다. 로컬에서 실행되는 모델을 사용하면 프롬프트도 컴퓨터 밖으로 나가지 않습니다.

다음 단계

시작하기설치부터 첫 작업까지 진행합니다.연결 방식 보기클라이언트 연결 방법을 확인합니다.

작동 방식 ​

전체 흐름 ​

데몬이 소유하는 상태 ​

클라이언트 연결 ​

클라이언트 선택 ​

저장 위치 확인하기 ​