Raspberry Pi와 대화하기 — Garudust를 사용하여 Telegram으로 GPIO 제어, 센서 읽기 및 서비스 관리하기

당신의 Raspberry Pi는 집에서 센서 데이터를 기록하거나, 릴레이(Relay)를 구동하거나, 홈 어시스턴트(Home Assistant) 스크립트를 실행하는 등 유용한 작업을 수행하며 자리 잡고 있습니다. 당신은 외출 중입니다. 상태를 확인하고 싶습니다.

예전에는 노트북에서 SSH로 접속했습니다. 이제는 그저 Telegram을 열고 물어보기만 하면 됩니다.

당신: 온도 센서가 여전히 작동하고 있나요?
에이전트: ✓ 실행됨: cat /sys/bus/w1/devices/28-*/w1_slave
        현재 온도: 24.3°C — 센서가 정상적으로 응답하고 있습니다.
...

이것은 SSH 샌드박스(Sandbox)를 갖춘 Garudust Agent입니다. 에이전트는 클라우드 VPS(또는 인터넷 접속이 가능한 모든 서버)에서 실행됩니다. 당신은 Telegram을 통해 채팅합니다. 에이전트는 당신의 Pi에 SSH로 접속하여 필요한 작업을 실행합니다. 당신의 Pi에는 SSH가 활성화되어 있기만 하면 됩니다. 에이전트를 위한 추가 소프트웨어나 포트 포워딩(Port Forwarding)은 필요하지 않습니다.

작동 원리

당신 (Telegram)
    │
    ▼
...

에이전트의 terminal 도구는 보통 명령어를 로컬에서 실행합니다. terminal_sandbox: ssh 설정을 사용하면, 모든 명령어가 대신 ssh를 통해 Pi로 전달됩니다. 에이전트는 이를 알지 못하며 신경 쓰지도 않습니다 — 에이전트는 여전히 동일한 도구를 호출합니다. 라우팅은 샌드박스 계층에서 투명하게 이루어집니다.

사전 요구 사항

• SSH가 활성화된 Raspberry Pi (모든 모델, 최신 Raspberry Pi OS 가능)
• Garudust를 실행할 서버 — 5달러짜리 VPS, 네트워크상의 다른 기기, 또는 localhost를 가리키는 Pi 자체도 가능
• Telegram 봇 토큰 (@BotFather로부터 발급)
• 서버에 설치된 Garudust

# 서버에서 — Garudust 설치
curl -LO "https://github.com/garudust-org/garudust-agent/releases/latest/download/garudust-$(curl -s https://api.github.com/repos/garudust-org/garudust-agent/releases/latest | grep tag_name | cut -d'"' -f4)-x86_64-unknown-linux-musl.tar.gz"
tar -xzf garudust-*.tar.gz && sudo mv garudust garudust-server /usr/local/bin/

1단계 — 전용 SSH 키 설정

에이전트에 개인 SSH 키를 절대 사용하지 마세요. 서버에 전용 키를 생성하십시오:

ssh-keygen -t ed25519 -f ~/.ssh/garudust_pi -N "" -C "garudust-agent"

공개 키(Public Key)를 Pi로 복사하십시오:

ssh-copy-id -i ~/.ssh/garudust_pi.pub pi@192.168.1.50
# 또는 Pi가 아직 동일한 네트워크에 있지 않은 경우:
# cat ~/.ssh/garudust_pi.pub | ssh pi@<pi-ip> "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

비밀번호 입력 프롬프트 없이 작동하는지 확인하십시오:

ssh -i ~/.ssh/garudust_pi -o BatchMode=yes pi@192.168.1.50 "echo OK"
# → OK

2단계 — Garudust 설정

~/.garudust/.env:

ANTHROPIC_API_KEY=sk-ant-...       # 또는 지원되는 다른 제공업체
TELEGRAM_TOKEN=123456789:AAFxxx    # 귀하의 봇 토큰

~/.garudust/config.yaml:

security:
  approval_mode: smart             # 읽기 전용 명령은 자동 승인, 쓰기 작업은 먼저 확인 요청
  terminal_sandbox: ssh
...

@userinfobot에게 메시지를 보내 귀하의 Telegram 사용자 ID를 찾으십시오.

서버를 시작하십시오:

garudust-server

이제 할 수 있는 것들

센서 데이터 읽기

DS18B20 온도 센서 (1-Wire):

나:    temperature?
에이전트:  24.3°C

나:    1분 동안 10초마다 온도를 기록하고 평균을 알려줘
에이전트:  ✓ 실행됨: for i in $(seq 6); do cat /sys/bus/w1/devices/28-*/w1_slave | grep t= | awk -F= '{print $2/1000}'; sleep 10; done
        측정값: 24.1, 24.2, 24.3, 24.3, 24.4, 24.2
...

DHT22 습도 + 온도:

나:    DHT22의 습도와 온도
에이전트:  ✓ 실행됨: python3 ~/scripts/dht22_read.py
        Temperature: 24.3°C  Humidity: 58.2%

GPIO 제어 (릴레이, LED, 모터)

나:    정원 조명을 켜줘 (GPIO 18 릴레이 켜기)
에이전트:  ⚠ 이것은 GPIO 상태를 변경합니다 — 확인하시겠습니까?
나:    yes
...

시스템 상태 확인

나:    Pi 상태는 어때?
에이전트:  ✓ 실행됨: vcgencmd measure_temp && free -h && df -h / && uptime
        CPU temp:    52.1°C
...

서비스 관리

나:    homebridge 재시작해줘
에이전트:  ⚠ 이것은 homebridge 서비스를 재시작합니다 — 확인하시겠습니까?
나:    y
...

자신만의 스크립트 실행

에이전트는 이미 Pi에 있는 어떤 스크립트든 실행할 수 있습니다. 에이전트에게 명령어를 가르칠 필요는 없습니다. 단지 원하는 내용을 설명하기만 하면 됩니다:

사용자: 식물에 30초 동안 물을 줘
에이전트: ✓ 실행됨: python3 ~/scripts/sprinkler.py on 30
        밸브가 열렸습니다. 30초 후에 닫힙니다.
...

Cron으로 자동화하기

채팅창에 머물러 있지 않아도 반복적인 점검을 설정할 수 있습니다:

# config.yaml
cron:
  timezone: "Asia/Bangkok"
...

이제 에이전트가 먼저 당신에게 메시지를 보냅니다. 굳이 물어볼 필요가 없습니다.

보안 참고 사항

이 시스템을 배포하기 전에 알아두어야 할 몇 가지 사항이 있습니다:

SSH 연결은 자동으로 강화됩니다. Garudust는 BatchMode=yes(비밀번호 프롬프트 없음), StrictHostKeyChecking=accept-new(MITM 공격을 방지하기 위해 변경된 호스트 키 거부)를 사용하며, ssh를 실행하기 전에 서브프로세스 환경을 정리하여 API 키나 비밀 정보가 Pi에 전달되지 않도록 합니다.

승인 모드(Approval mode)가 파괴적인 명령어를 차단합니다. approval_mode: smart 설정 시, 읽기 전용 명령어(센서 읽기, 로그 확인, git status)는 묻지 않고 실행됩니다. 상태를 변경하는 모든 작업은 먼저 확인을 요청합니다. approval_mode: auto 설정은 테스트를 마친 후 본인에게만 적용하십시오.

더 높은 보안을 원한다면 pi 사용자를 잠그십시오. authorized_keys에서 command=를 사용하여 SSH 키를 특정 명령어로 제한하거나, 에이전트의 SSH 사용자를 호출에 필요한 스크립트만 가진 전용 계정에서 실행하십시오.

Pi는 인터넷에 포트를 절대 노출하지 않습니다. 에이전트가 서버에서 Pi로 SSH 접속을 수행합니다(SSHes out). 즉, Pi는 전 세계가 아닌 당신의 서버에 대해서만 22번 포트가 열려 있으면 됩니다.

다음 단계

• 여러 대의 Pi — 서로 다른 에이전트 세션을 서로 다른 호스트로 지정하거나, 요청 내용에 따라 적절한 Pi로 SSH 접속하는 얇은 래퍼(wrapper) 스크립트를 만드세요.
• 음성 제어 — iApp TTS와 결합하여 Pi에 연결된 스피커를 통해 음성 응답을 받으세요.
• 기술 학습 (Skill learning) — 워크플로우를 몇 번 실행하고 나면, Garudust가 이를 재사용 가능한 기술(skill)로 자동 기록하므로 더 이상 단계별로 설명할 필요가 없습니다.

Garudust의 전체 소스 코드는 garudust-org/garudust-agent에서 확인할 수 있습니다. SSH 샌드박스 (SSH sandbox) 기능은 v0.13 버전에 도입되었습니다. Releases에서 최신 바이너리 (binary)를 내려받거나, cargo build --release 명령어를 통해 소스 코드로부터 직접 빌드할 수 있습니다.