Stavrobot

Stavrobot은 "AI 어시스턴트에게 필요한 만큼의 접근 권한만, 그 이상은 없다"는 원칙으로 만들어진 개인 AI 어시스턴트입니다.

AI 어시스턴트의 모든 유용한 기능을 갖추고 있으면서도 샌드박싱, 격리, 최소 권한에 중점을 둡니다. 가볍고 docker compose up만으로 배포됩니다.

기능

• 안전함. 모든 것이 컨테이너 안에서 실행되며, 호스트 OS는 AI에게 완전히 보이지 않습니다. AI는 여러분이 원하지 않는 한 어떤 비밀도 볼 수 없습니다.
• 가벼움. 컴포넌트마다 컨테이너를 하나씩 실행하지 않습니다. 모든 플러그인이 단일 컨테이너 안에서 Unix 권한으로 분리되어 실행됩니다.
• 원하는 모델을 사용하세요. 로컬, OpenRouter, Anthropic/OpenAI. Pi가 지원하는 것이라면 무엇이든 봇이 사용할 수 있습니다.
• Signal/Telegram/WhatsApp/Email 통합. 포매팅, 첨부 파일 등을 지원하는 양방향 메시징.
• Pebble Index 통합. 링 녹음을 에이전트에 직접 대기시킬 수 있습니다.
• 3계층 지식. 컨텍스트를 터뜨리지 않고 모든 것을 기억합니다. 메모리에서 지능적이고 투명하게 데이터를 검색합니다.
• 낮은 토큰 사용량. 토큰 사용량을 가볍게 유지하기 위한 다양한 최적화가 적용되었습니다. 내부적으로 TOON까지 사용합니다.
• 플러그인. git 저장소 URL만 알려주면 플러그인을 설치하고 Stavrobot의 기능을 확장할 수 있습니다. 플러그인은 서로 격리되어 있으며, 각각 전용 시스템 사용자로 실행되어 다른 플러그인의 파일이나 설정에 접근할 수 없습니다.
• 서브에이전트. 메인 에이전트는 자체 대화 컨텍스트, 시스템 프롬프트, 제한된 도구 접근 권한을 가진 서브에이전트를 만들 수 있습니다. 외부 사람과 대화하여 작업을 완료하거나 일을 주선할 때, 외부 사람과 메인 에이전트 사이에 완충 역할을 두는 데 유용합니다.
• 자기 프로그래밍. 에이전트가 스스로를 프로그래밍하고 확장할 수 있습니다.
• 샌드박스 Python 실행. uv를 통한 pip 의존성을 포함한 임의의 Python을 호스트 환경과 격리하여 실행합니다.
• 스케줄링. 에이전트가 자체적으로 반복 또는 일회성 작업을 예약할 수 있습니다.

빠른 시작

AI 지원 설치: 코딩 AI(Claude Code, Cursor, Windsurf 등)에게 https://stavrobot.stavros.io/INSTALL.md를 가져와 따르라고 하세요 — 전체 설정을 대화식으로 안내해 줍니다.

수동 설치:

1. Telegram에서 @BotFather에게 메시지를 보내 봇을 만들고 토큰을 복사하세요. @userinfobot에게 메시지를 보내 Telegram 사용자 ID를 받으세요(이것이 채팅 ID로 사용됩니다).

2. env.example을 .env로 복사하고 **POSTGRES_PASSWORD**를 안전한 값으로, TZ를 여러분의 시간대로 변경하세요.

3. config.example.toml을 data/main/config.toml로 복사하고 필수 필드를 채우세요: apiKey, password, publicHostname, [owner].name, [owner].telegram(여러분의 채팅 ID), [telegram].botToken. 파일의 나머지 항목은 모두 선택 사항입니다.

4. docker compose up --build

이게 전부입니다. Telegram에서 봇에게 메시지를 보내면 응답합니다. Signal, WhatsApp, 이메일 및 기타 옵션에 대해서는 아래의 자세한 설정 섹션을 참조하세요.

설정

구성

1. config.example.toml을 data/main/config.toml로 복사하세요.
2. API 키와 설정을 채우세요. 예제 파일에는 각 섹션을 설명하는 주석이 있습니다.
3. 최소한 authFile(또는 apiKey)과 publicHostname을 설정하세요. 나머지는 모두 선택 사항입니다.
4. env.example을 .env로 복사하고 시간대(TZ)를 설정하세요. Postgres 자격 증명 및 기타 환경 설정도 여기에서 재정의할 수 있습니다. 항상 POSTGRES_PASSWORD를 안전한 값으로 설정하세요 — 기본값은 취약한 자리 표시자이며 프로덕션에서 사용해서는 안 됩니다.

구성 편집기

앱이 시작된 후 /settings/config를 열면 브라우저에서 config.toml을 편집할 수 있습니다. 이 페이지는 HTTP Basic Auth로 보호되며, 포함된 비밀을 포함한 원시 구성을 표시합니다. 유효한 저장은 단일 <CONFIG_PATH>.bak 백업을 생성하고, 새 내용을 저장한 뒤 앱을 재시작합니다. 이 과정에서 진행 중인 에이전트 턴이 중단됩니다.

plugin-runner, coder, signal-bridge, python-runner는 시작할 때만 config.toml을 읽습니다. 비밀번호처럼 이들에 영향을 주는 변경 사항은 해당 컨테이너를 수동으로 재시작해야 합니다.

사용자 정의 및 OpenAI 호환 엔드포인트

Stavrobot은 config.toml에서 baseUrl을 설정하여 모든 OpenAI 호환 엔드포인트(Ollama, LiteLLM, vLLM 등) 또는 사용자 정의 Anthropic 호환 프록시를 가리킬 수 있습니다. 필수 필드와 예제 구성은 config.example.toml을 참조하세요. reasoning = true는 사고를 지원하는 모델에만 설정하세요. 이것이 사용자 정의 엔드포인트에서 thinkingLevel이 적용되게 하는 요소이기 때문입니다.

인증

앱은 두 가지 인증 모드를 지원합니다: API 키 또는 OAuth.

• API 키: config.toml에서 apiKey를 설정하세요. 로그인이나 로그아웃이 필요 없습니다.
• OAuth: config.toml에서 authFile을 설정하세요(자격 증명이 저장될 경로). 로그인 페이지는 Pi가 지원하는 모든 OAuth 제공자와 작동합니다.
  • 로그인: 브라우저에서 <your-hostname>/login을 방문하세요. 페이지의 안내를 따르면 자격 증명이 인증 파일에 저장됩니다. Stavrobot은 제공자의 헤드리스 로그인 방식을 선택하므로, 접근할 수 없는 localhost 콜백으로 리디렉션되는 일이 없습니다. Anthropic의 경우 Authorize를 선택하면 Anthropic이 코드를 표시하며, 이를 복사하여 Stavrobot 로그인 페이지에 붙여넣습니다. 디바이스 코드 흐름을 사용하는 제공자는 대신 Stavrobot 페이지에 코드를 표시하며, 여러분이 제공자 사이트에 입력합니다. 봇이 실행 중일 때 인증이 만료되면, 메시징 플랫폼을 통해 로그인 URL이 담긴 메시지를 보냅니다.
  • 로그아웃: authFile 경로의 파일을 삭제하세요. 봇은 다음 메시지에서 자격 증명 누락을 감지하고 다시 로그인하라는 메시지를 표시합니다.

Claude Code 설정

coder 컨테이너는 선택 사항입니다(자기 프로그래밍 기능에만 필요). 기본적으로 구독 인증(OAuth)을 사용하는 Claude Code를 사용하며, 이는 메인 앱의 API 키와 별개입니다. 대신 Anthropic 호환 API 엔드포인트를 사용하려면 config.toml에서 [coder].apiKey와 [coder].baseUrl을 모두 설정하세요. 그러면 Claude Code가 이를 ANTHROPIC_API_KEY와 ANTHROPIC_BASE_URL로 사용합니다. 최상위 apiKey/baseUrl은 메인 앱의 모델만 구성하며 coder에는 절대 영향을 주지 않습니다. 두 [coder] 키 중 하나만 설정하면 시작 오류가 발생합니다.

Docker Compose 프로필은 쉼표로 구분되므로 조합할 수 있습니다(예: COMPOSE_PROFILES=signal,coder).

1. .env 파일에서 COMPOSE_PROFILES에 coder를 포함하도록 설정하세요(예: COMPOSE_PROFILES=coder, 또는 Signal도 사용하는 경우 COMPOSE_PROFILES=signal,coder).
2. 컨테이너를 시작하세요: docker compose --profile coder up --build
3. 로그인하세요([coder].apiKey/[coder].baseUrl을 설정한 경우 이 단계와 다음 단계를 건너뛰세요): docker compose exec -u coder coder claude(로그인하지 않았다면 로그인하라는 메시지가 표시됩니다).
4. 브라우저 기반 OAuth 흐름을 따르세요.
5. 구성에서 [coder].model을 Claude Code 모델 별칭(sonnet, opus, haiku)으로 설정하세요.

Signal 설정

Signal은 별도의 전화번호가 필요합니다 — 개인 번호가 아닙니다. 선불 SIM이나 VoIP 번호도 작동합니다.

1. .env 파일에서 COMPOSE_PROFILES=signal의 주석을 해제하여 signal-bridge 컨테이너를 활성화하세요.
2. 컨테이너를 빌드하세요: docker compose --profile signal build
3. 컨테이너에 Signal을 등록하세요(하나 선택):
   • 기존 Signal 계정에 연결: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli link -n "Stavrobot" | tee >(xargs -L 1 qrencode -t utf8)' — 휴대폰으로 QR 코드를 스캔하세요(Signal > 설정 > 연결된 기기).
   • 새 번호 등록: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER register', 그런 다음 docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER verify CODE'로 인증하세요.
4. 구성에서 [signal].account를 설정하세요.
5. 컨테이너를 시작하세요: docker compose up --build
6. 첫 시작 후 /settings 웹 UI를 통해 허용된 번호를 추가하세요.
7. 중요: signal-cli는 아직 메시지를 보내지 않은 연락처의 전화번호를 확인하지 않습니다. 봇이 해당 연락처로부터 오는 메시지를 수신하고 식별하려면, 먼저 각 연락처에 전화번호로 첫 메시지를 보내야 합니다. 소유자에 대해 이를 트리거하려면 다음을 실행하세요:

   docker compose exec app node -e "fetch('http://localhost:3001/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:'Send the message \"Hello from Stavrobot\" to my Signal number.'})}).then(r=>r.text()).then(console.log)"
   

8. 자세한 내용은 signal-cli quickstart를 참조하세요.

Telegram 설정

1. Telegram에서 @BotFather에게 메시지를 보내 새 봇을 만들고 토큰을 복사합니다.
2. Telegram에서 @userinfobot에게 메시지를 보내 사용자 ID를 확인합니다(이 ID가 채팅 ID로 사용됩니다).
3. config의 [telegram].botToken을 설정합니다.
4. config의 [owner].telegram에 채팅 ID(휴대폰 번호가 아님)를 설정합니다.
5. 첫 시작 후 /settings 웹 UI를 통해 허용할 채팅 ID를 추가합니다.
6. Stavrobot은 앱이 시작되면 자동으로 Telegram을 롱 폴링하여 업데이트를 수신합니다.

WhatsApp 설정

WhatsApp은 별도의 전화번호가 필요합니다. 그렇지 않으면 자기 자신에게 메시지를 보내게 되어 제대로 작동하지 않습니다.

WhatsApp은 Baileys를 사용합니다. 이는 WhatsApp Web처럼 컴패니언 기기로 연결되는 비공식 WhatsApp Web 라이브러리입니다. 별도의 전화번호는 필요하지 않으며 기존 WhatsApp 계정에 연결됩니다.

위험: Baileys는 비공식 API를 사용합니다. WhatsApp은 이를 사용하는 계정을 차단할 수 있습니다. 사용에 따른 책임은 본인에게 있습니다.

1. config.toml에 [whatsapp] 섹션을 추가합니다(형식은 config.example.toml 참조).
2. 컨테이너를 시작합니다: docker compose up --build
3. 앱 로그에 QR 코드가 나타납니다(docker compose logs -f app).
4. 휴대폰에서 WhatsApp을 열고 연결된 기기로 이동하여 QR 코드를 스캔합니다.
5. 세션은 ./data/whatsapp에 저장되어 재시작 후에도 유지됩니다.
6. /settings 웹 UI를 통해 허용할 전화번호를 추가합니다.

이메일 설정

이메일은 수신 전달에 Cloudflare Email Worker를, 발신에 SMTP를 사용합니다. 전체 worker 코드와 자세한 설정 방법은 config.example.toml을 참조하세요.

1. config.toml에 SMTP 자격 증명과 임의의 webhookSecret이 포함된 [email] 섹션을 추가합니다.
2. Cloudflare Email Worker(config.example.toml에 코드 있음)를 배포하고 worker에 WEBHOOK_URL 및 WEBHOOK_SECRET 환경 변수를 설정합니다.
3. Cloudflare Email Routing에서 수신 메일을 worker로 전달하는 규칙을 추가합니다.
4. /settings 웹 UI를 통해 허용할 발신자 주소를 추가합니다.

Pebble Index 설정

Pebble Index가 Stavrobot에 설정된 비밀번호를 사용한 HTTP Basic 인증으로 POST /pebble-index/webhook에 링 웹훅을 보내도록 구성합니다. 멀티파트 요청에는 recordedAt(에포크 밀리초)과 client가 포함되어야 하며, transcription과 audio/mp4 audio 파일을 포함할 수 있습니다. 오디오 녹음은 .m4a 첨부 파일로 에이전트의 대기열에 추가됩니다.

실행

docker compose up --build