geode serve는 REPL 없이 도는 헤드리스 게이트웨이 데몬입니다. 메신저 receiver, 스케줄러, 선택적 웹훅, 그리고 thin CLI가 붙는 IPC 소켓을 한 프로세스에서 호스팅합니다.
데몬이 띄우는 것
| 구성 요소 | 역할 | 코드 경로 |
|---|---|---|
| 메신저 receiver | Slack은 Socket Mode push로, Discord와 Telegram은 polling으로 메시지를 받아 에이전트 세션에 라우팅합니다. --poll/-p는 poll 기반 경로에만 적용됩니다. | core/cli/typer_serve.py |
| 스케줄러 | 예약 작업을 로드하고, 놓친 실행을 복구하고, 주기 실행합니다. | core/cli/typer_serve.py |
| 웹훅 (선택) | webhook_enabled일 때 HTTP 엔드포인트를 엽니다. | core/server/supervised/webhook_handler.py |
| CLI IPC 소켓 | ~/.geode/cli.sock Unix 소켓. thin CLI의 자유 텍스트와 슬래시 명령이 여기로 들어옵니다. | core/server/ipc_server/poller.py |
대부분은 직접 띄울 필요가 없습니다
geode를 실행하면 소켓을 확인하고, 데몬이 없으면 백그라운드로 자동 시작한 뒤 IPC로 붙습니다 (core/cli/ipc_client.py). 대화만 할 거라면geode serve를 직접 칠 일이 없습니다. 직접 실행은 메신저와 스케줄을 명시적으로 운영할 때의 선택지입니다.
시작 조건: gateway_enabled
geode serve는 gateway_enabled가 꺼져 있으면 시작을 거부하고 안내를 출력합니다. 켜려면~/.geode/.env에 한 줄을 추가합니다.
# ~/.geode/.env GEODE_GATEWAY_ENABLED=true
geode serve # 포그라운드 실행 geode serve --poll 5 # poll 기반 receiver 주기 5초
종료와 상태: 있는 그대로
geode serve stop 같은 서브커맨드는 없습니다. 종료는 프로세스에 직접 시그널을 보냅니다.
| 하고 싶은 것 | 명령 |
|---|---|
| 데몬 종료 | pkill -f "geode serve". ps aux | grep은 긴 파이썬 경로가 잘려 못 잡는 경우가 있으니 pgrep -f 계열을 씁니다. |
| 살아 있는지 확인 | pgrep -f "geode serve", 또는 geode about의 데몬 소켓 상태. |
| 상태 자세히 | REPL 안에서 /status. 데몬, 모델, MCP, 디스크 사용량을 보여줍니다. |
| 업데이트 + 재시작 | geode update. uv tool이면 현재 major/minor의 최신 patch를 설치하고, editable 설치면 실제 GEODE 소스 체크아웃을 갱신합니다. 데몬이 돌고 있었으면 새 코드로 다시 띄웁니다. minor/major 패키지 업데이트는 --latest를 명시합니다. |
SIGTERM을 받으면 데몬은 단계적으로 내려갑니다. 새 요청 수락 중지, 30초 세션 드레인, 스케줄러 저장과 정지, MCP 종료, 게이트웨이 정지 순서입니다 (core/cli/typer_serve.py).
실패 모드
| 증상 | 원인 | 해법 |
|---|---|---|
geode serve가 시작을 거부 | gateway 비활성 | ~/.geode/.env에 GEODE_GATEWAY_ENABLED=true를 추가합니다. |
| 배너 모델과 응답 모델이 다름 | 업데이트 전의 오래된 데몬이 살아 있음 | pkill -f "geode serve"로 전부 내리고 geode를 다시 실행합니다. |
| 동작이 들쭉날쭉, 소켓 충돌 | 데몬 여러 개가 ~/.geode/cli.sock을 두고 경합 | pgrep -f "geode serve"로 개수를 확인하고 전부 종료 후 하나만 띄웁니다. |
| /model을 바꿔도 데몬이 옛 모델 유지 | 데몬 환경에 모델 env가 박제됨 (구버전 잔재) | 데몬은 시작 시 모델 계열 env 키를 버리는 것이 기본입니다. 데몬을 재시작하고, 그래도 안 되면 geode config explain model을 봅니다. |
설정 레퍼런스
- Serve와 게이트웨이. receiver, 바인딩, lane queue 운영.
- 메신저 연동. Slack, Discord, Telegram 연결.
- 작업 예약. 자연어와 cron 예약.
- 라이프사이클. 부트스트랩과 종료 순서의 내부.