Odysseus

───────────────────────────────────────────────
⊹ ࣪ ˖ ૮( ˶ᵔ ᵕ ᵔ˶ )っ Odysseus 버전 1.0
───────────────────────────────────────────────

셀프 호스팅 (self-hosted) AI 워크스페이스 -- ChatGPT와 Claude에서 경험할 수 있는 UI 경험의 셀프 호스팅 버전을 지향합니다. 하지만 더 투박하고 재미있게 만들었습니다. 여러분의 자체 하드웨어에서, 여러분의 데이터로 실행됩니다 -- 로컬 우선 (local-first), 개인정보 보호 우선 (privacy-first), 그리고 트로이 목마(trojan)는 없습니다.

주요 기능 (Features)

채팅 (Chat) -- 모든 로컬 모델 또는 API와 채팅하세요. 추가하는 방법은 매우 간단합니다. 　vLLM · llama.cpp · Ollama · OpenRouter · OpenAI
에이전트 (Agent) -- 도구를 부여하고 전체 작업을 스스로 수행하게 하세요. 　opencode 기반 · MCP · 웹 (web) · 파일 (files) · 셸 (shell) · 기술 (skills) · 메모리 (memory)
쿡북 (Cookbook) -- 하드웨어를 스캔하고, 모델을 추천하며, 클릭 한 번으로 다운로드 및 서빙(serve)합니다.. 정말 쉽습니다! 　llmfit 기반 · VRAM 인지 (VRAM-aware) · GGUF / FP8 / AWQ · 적합도 점수 (fit scoring) · vLLM / llama.cpp 서빙
딥 리서치 (Deep Research) -- 정보를 수집, 읽기 및 합성하여 멋진 시각적 보고서로 만드는 다단계 실행 프로세스입니다. 　Tongyi DeepResearch에서 변형
비교 (Compare) -- 모델들을 나란히 놓고 비교할 수 있는 재미있는 도구입니다.

완전한 블라인드 테스트로 편향 없이 테스트하세요! 　멀티 모델 (multi-model) · 블라인드 테스트 (blind test) · 합성 (synthesis)

문서 (Documents) -- 당신이 텍스트를 작성하며, AI는 그 반대가 아닌 보조를 위해 존재합니다. 　멀티 탭 에디터 (multi-tab editor) · 마크다운 (markdown) · HTML · CSV · 구문 강조 (syntax highlighting) · AI 편집 (AI edits) · 제안 (suggestions)
메모리 / 기술 (Memory / Skills) -- 지속적인 메모리와 기술을 통해, 에이전트가 당신과 당신의 작업을 더 잘 이해함에 따라 시간이 흐를수록 진화합니다! 　ChromaDB · fastembed (ONNX) · 벡터 + 키워드 검색 (vector + keyword retrieval) · 가져오기/내보내기 (import/export)
이메일 (Email) -- AI 분류 기능이 내장된 IMAP/SMTP 편지함: 긴급 알림, 자동 태그, 자동 요약, 자동 답장 초안, 자동 스팸 처리. 　IMAP · SMTP · 계정별 라우팅 (per-account routing) · CalDAV 지원 (CalDAV-aware)
노트 및 작업 (Notes & Tasks) -- 알림 기능이 있는 빠른 노트, 할 일 목록, 그리고 에이전트가 수행할 수 있는 예약된 작업. 　노트 핑 (note pings) · 체크리스트 (checklist) · cron 방식 작업 (cron-style tasks) · ntfy / 브라우저 / 이메일 채널
캘린더 (Calendar) -- Radicale / Nextcloud / Apple / Fastmail과 CalDAV 동기화를 지원하는 로컬 우선 (Local-first) 캘린더. 　CalDAV 가져오기 (pull) · .ics 가져오기/내보내기 (import/export) · 캘린더별 색상 · 에이전트 인식 (agent-aware)
모바일 작동 (Works on mobile) -- 데스크톱뿐만 아니라 휴대폰에서도 훌륭하게 보이고 작동합니다. 　반응형 (responsive) · 설치 가능 (PWA) · 터치 제스처 (touch gestures)
기타 (Extras) -- 더 탐색할 수 있는 기능들이 많습니다. 직접 사용해 보시길 권장합니다! 　이미지 에디터 (image editor) · 테마 에디터 (theme editor) · 파일 업로드 (vision + PDF) · 웹 검색 (web search) · 프리셋 (presets) · 세션 (sessions) · 2단계 인증 (2FA)

데모 (Demo)

랜딩 페이지(docs/index.html)에서 마우스를 올려 실행할 수 있는 전체 투어를 제공합니다. 몇 가지 모습은 다음과 같습니다:

채팅 및 에이전트 (Chat & Agents)

딥 리서치 (Deep Research)

비교 (Compare)

문서 (Documents)

노트 및 작업 (Notes & Tasks)

빠른 시작 (Quick Start)

기본 설정은 즉시 작동합니다 — 클론(clone)하고, 실행하고, 앱 내부에서 구성하세요.
첫 로그인 후 설정 (Settings) 패널을 열어 Odysseus를 사용자의 LLM 서버, 검색 제공자(search provider), 이메일 계정 등으로 연결하세요. AUTH_ENABLED, DATABASE_URL, 또는 사전 시드(pre-seed)용 ODYSSEUS_ADMIN_PASSWORD와 같이 배포 수준의 설정을 재정의해야 하는 경우에만 .env 파일을 수정하세요 (그렇지 않으면 초기 비밀번호가 생성되어 첫 부팅 시 출력됩니다).

옵션 1: Docker (권장)

git clone <your-odysseus-repo-url>
cd odysseus
cp .env.example .env       # 선택 사항이지만 명시적인 기본값 설정을 위해 권장됨
...

Compose는 Odysseus, ChromaDB, SearXNG, 그리고 ntfy를 시작합니다. 첫 실행 시 전체 이미지 빌드(image build)를 수행합니다. 컨테이너가 정상(healthy) 상태가 되면 http://localhost:7000을 여세요.

Cookbook 원격 서버는 Docker 내부의 ./data/ssh에 있는 Odysseus 소유의 SSH 키를 사용합니다. Cookbook -> Settings -> Servers에서 공개 키(public key)를 생성/복사하여 원격 서버의 ~/.ssh/authorized_keys에 추가하세요. 키를 생성한 후, 호스트에서 다음 명령어로 설치할 수도 있습니다:

ssh-copy-id -i data/ssh/id_ed25519.pub user@server

Cookbook 로컬 다운로드 파일은 ./data/huggingface에 저장되며, Odysseus 컨테이너 내부의 ~/.cache/huggingface로 마운트(mount)됩니다.

유용한 확인 사항:

docker compose ps
docker compose logs --tail=120 odysseus
docker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED'
...

Docker에서 예상되는 벡터 메모리(vector-memory) 시작 라인:

ChromaDB connected: chromadb:8000
MemoryVectorStore initialized

Cookbook 모델 카탈로그 확인 시 0이 아닌 숫자가 출력되어야 합니다. 만약 0이 출력된다면, docker compose build --no-cache odysseus 명령어로 Odysseus 이미지를 다시 빌드하세요.

옵션 2: 수동 설치 — Linux / macOS

요구 사항: Python 3.11 이상. Linux/Termux의 경우, Cookbook은 백그라운드 모델 다운로드 및 서빙을 위해 tmux를 추가로 요구합니다.

먼저 시스템 패키지를 설치하세요:

# Debian/Ubuntu
sudo apt install tmux

...

그 다음 Odysseus를 설치하세요:

git clone <your-odysseus-repo-url>
cd odysseus
python3 -m venv venv
...

옵션 3: 수동 설치 — Windows (PowerShell)

git clone <your-odysseus-repo-url>
cd odysseus
python -m venv venv
...

http://localhost:7000을 열고, 생성된 관리자(admin) 비밀번호로 로그인한 뒤, Settings (설정) 내에서 나머지 모든 사항을 구성하세요.

보안 주의 사항

Odysseus는 셸(shell) 액세스, 파일 업로드, 모델 다운로드, 웹 리서치, 이메일/캘린더 통합, API 토큰 등 강력한 로컬 도구를 갖춘 셀프 호스팅 (self-hosted) 워크스페이스입니다. 이를 관리자 콘솔(admin console)처럼 취급하십시오.

네트워크 접근이 가능한 모든 배포 환경에서는 AUTH_ENABLED=true를 유지하세요.
HTTPS와 신뢰할 수 있는 리버스 프록시 (reverse proxy) 없이 공용 인터넷에 직접 노출하지 마세요.
data/, .env, 로그, 데이터베이스, 업로드/생성된 미디어는 Git에서 제외하세요. 기본적으로 무시(ignore)되도록 설정되어 있습니다.
첫 부팅 후 data/auth.json을 검토하세요: 의도한 경우가 아니라면 공개 회원가입(open signup)을 비활성화하고, 본인의 계정만 관리자(admin)로 설정하며, 데모/테스트 계정은 관리자 권한을 주지 마세요.
관리자가 아닌 사용자는 기본적으로 셸/Python/파일 읽기/쓰기 권한을 갖지 않으며, MCP 관리, API 토큰, 웹훅 (webhooks), 모델/쿡북 (cookbook) 서빙, 백업/볼트 (backup/vault), 앱 설정과 같은 관리자 전용 경로 및 도구는 관리자 권한으로 제한됩니다. 다른 기능들은 사용자별 권한에 의해 제어되므로, 배포를 공개하기 전에 각 사용자의 권한을 검토하세요.
공유된 채팅, 데모, 스크린샷 또는 로그에 붙여넣은 적이 있는 모든 API 키나 토큰은 교체(rotate)하세요.
API 토큰이나 웹훅을 활성화하는 경우, 통합 항목별로 별도의 토큰을 생성하고 사용하지 않는 토큰은 삭제하세요.
수동 개발 실행 시에는 127.0.0.1에 바인딩(binding)하는 것을 권장합니다. LAN/리버스 프록시 액세스를 의도하는 경우에만 0.0.0.0에 바인딩하세요.
포크(fork)를 공개하기 전에 git status --short를 실행하여 .env, data/, logs/, 업로드 파일, 백업 또는 로컬 데이터베이스의 개인 파일이 스테이징(staged)되지 않았는지 확인하세요.

HTTPS 적용하기

Odysseus는 지정된 포트에서 일반 HTTP를 통해 서비스를 제공합니다. 이는 localhost나 신뢰할 수 있는 LAN/VPN 환경에서는 괜찮지만, 브라우저에서 경고("보안되지 않은 페이지에 비밀번호 필드가 있습니다")를 표시하며 로그인 정보와 API 토큰이 평문(cleartext)으로 전송됩니다. 다른 기기와 공유된 Tailscale IP를 포함하여, 사용자의 머신 외부에서 접근 가능한 환경이라면 반드시 앞에 TLS 종료(TLS-terminating) 리버스 프록시(reverse proxy)를 배치하세요.

Caddy를 사용하는 가장 짧은 경로 (Let's Encrypt 인증서를 자동 갱신합니다):

odysseus.example.com {
  reverse_proxy localhost:7000
}

LAN 전용 Tailscale 배포의 경우, Caddy + tailscale-cert 또는 내장된 MagicDNS HTTPS 기능을 모두 사용할 수 있습니다. nginx/Traefik 설정도 유사합니다. localhost:7000을 프록시하고, 프록시에서 TLS를 종료하도록 설정하세요. 설정이 완료되면 브라우저 경고가 사라지고 로그인이 암호화됩니다.

기여하기 (Contributing)

도움을 환영합니다. 가장 좋은 진입점은 신규 설치 테스트, 프로바이더 설정 버그 수정, 모바일/에디터 개선, 문서화, 그리고 작고 집중적인 리팩토링(refactor)입니다. 현재 도움이 필요한 목록은 ROADMAP.md를 참조하세요.

설정 (Configuration)

대부분의 설정은 앱 내부의 /setup 또는 Settings에서 수행됩니다. 배포 수준의 기본값이나 첫 부팅 전에 적용되어야 하는 비밀 값(secrets)은 .env를 사용하세요. 주요 설정은 다음과 같습니다:

변수 (Variable)	기본값 (Default)	설명 (Description)
`LLM_HOST`	`localhost`	사용자의 LLM 서버 (예: `llm-host.local:8000`)
...

번들 서비스 (Bundled services)

Docker Compose에는 기본적으로 다음 서비스들이 포함되어 있습니다:

ChromaDB → 의미론적 메모리(semantic memory)를 위한 벡터 스토어(vector store). Docker 환경에서 Odysseus는 chromadb:8000으로 연결되며, 호스트에서는 localhost:8100으로 노출됩니다.
SearXNG → 웹 검색을 위한 메타 검색(meta search). Docker 환경에서 Odysseus는 searxng:8080으로 연결되며, 호스트에서는 127.0.0.1:8080으로만 노출됩니다.
ntfy → 로컬 알림 서비스, localhost:8091로 노출됩니다.

선택적 외부 서비스 (Optional external services)

Ollama → 로컬 LLM 서버 -- ollama.ai

아키텍처 (Architecture)

app.py                   # FastAPI 엔트리 포인트 (entry point)
core/      인증 (auth), 데이터베이스 (database), 미들웨어 (middleware), 상수 (constants)
src/       llm_core, 에이전트 루프 (agent_loop), 에이전트 도구 (agent_tools), 채팅 프로세서 (chat_processor), 검색 (search)/
...

데이터 (Data)

모든 사용자 데이터는 data/ 디렉토리에 저장됩니다 (gitignored):
app.db (세션 (sessions), 메시지 (messages), 문서 (documents)), memory.json, presets.json, uploads/, personal_docs/, chroma/, settings.json.

라이선스 (License)

MIT -- LICENSE 및 ACKNOWLEDGMENTS.md를 참조하세요.

Odysseus – 셀프 호스팅 AI 워크스페이스

요약

핵심 포인트