Talorys
당신만의 개인 AI 에이전트. 당신의 클라우드.
Talorys는 사용자의 자체 Cloudflare 계정 내부에서 완전히 실행되는 무료 오픈 소스 개인 AI 비서입니다. 별도의 서버, 데이터베이스 또는 Talorys 개발자가 운영하는 계정 없이도 사용자에게 대화하고, 중요한 내용을 기억하며, 작업(tasks), 메모(notes) 및 프로젝트를 관리하고, 예약된 알림과 루틴을 실행합니다.
한 사람. 하나의 Cloudflare 계정. 하나의 명령어. 하나의 개인 AI 에이전트.
npx create-talorys@latest
1. Talorys란 무엇인가
-
개인 비서(A private assistant) — 스트리밍 응답, Markdown 및 도구 활동 표시기(tool activity indicators)와 함께 대화할 수 있습니다.
-
메모리(Memory) — 사용자가 확인, 편집 및 삭제할 수 있는 영구적인 개인 사실과 선호도입니다. 각 턴마다 가장 관련성 높은 메모리만 모델로 전송됩니다.
-
작업, 메모 및 프로젝트(Tasks, notes and projects) — UI에서 완전한 CRUD가 가능하며, 채팅을 통해서도 (
-
브라우저는 오직 사용자의 *.pages.dev 사이트와만 통신합니다. /api/* 요청은 Pages Function을 실행하여 이를 **서비스 바인딩(service binding)**을 통해 에이전트 Worker로 전달합니다.
-
에이전트 Worker는 workers_dev: false 및 preview_urls: false로 배포되므로, 공개 URL이 없습니다.
-
인증 및 권한 부여는 프론트엔드가 아닌 Worker에서 처리됩니다.
-
채팅 응답은 서버 전송 이벤트(Server-Sent Events) 방식으로 종단 간 스트리밍됩니다.
더 자세한 내용은: docs/architecture.md.
3. 사용된 Cloudflare 서비스
| 서비스 | 용도 | 무료 플랜 지원 여부 |
|---|
| Cloudflare Pages | 프론트엔드 + Pages Function | 예 |
| ... | | |
| Talorys는 R2, D1, KV, Vectorize, AI Search, Workflows 또는 기타 유료 서비스를 사용하지 않습니다. | | |
4. 배포
npx create-talorys@latest
설치기는 다음을 수행합니다:
- Node.js (20.18 이상)를 확인하고, 번들된 Wrangler CLI를 사용합니다(전역으로 설치된
wrangler/cf는 감지되지만 필수는 아닙니다).
- Cloudflare 로그인을 확인하거나, 브라우저에서 Cloudflare의 인증 페이지를 엽니다.
- 계정을 선택할 수 있게 하고(여러 개가 있는 경우) 에이전트 이름을 지정하게 합니다.
- 소유자 비밀번호를 요청합니다(숨겨진 입력 필드이며, 강도 검사를 거칩니다). 이 비밀번호는 PBKDF2-SHA256으로 로컬에서 해시되어 Cloudflare 시크릿으로만 저장됩니다.
- 256비트 세션 시크릿과 고유 리소스 이름(
talorys-<id>-agent, talorys-<id>-web)을 생성합니다.
- 비공개 Worker를 배포하고(SQLite Durable Object를 생성), 비밀 정보를 저장하며, 서비스 바인딩이 포함된 Pages 프로젝트를 생성 및 배포합니다.
- AI 추론을 실행하지 않고도 라이브 배포(프론트엔드, 인증 엔드포인트, 미인증 거부, 스토리지 상태)를 확인합니다.
- Cloudflare가 보고하는 실제
https://….pages.dev URL을 출력합니다.
설치기는 talorys/ 디렉터리를 작성하며, 여기에는 talorys.json(설치 ID, 계정 ID, 리소스 이름, URL — 비밀 정보 없음)과 배포 가능한 아티팩트가 포함됩니다. 업데이트를 위해 이 파일을 보관하십시오.
중단되었나요? 같은 명령어를 같은 위치에서 다시 실행하세요. 이 명령어는 이미 존재하는 것을 조정합니다. 중복 리소스가 생기지 않으며, 비밀번호가 이미 설정된 경우 비밀번호 재입력을 요구하지 않고, 데이터는 절대 삭제되지 않습니다.
비대화형 설치: TALORYS_OWNER_PASSWORD=... npx create-talorys@latest --yes --account-id <id> (로그인하지 않은 경우 CLOUDFLARE_API_TOKEN을 설정해야 합니다).
권한(Permissions)
브라우저 로그인은 Wrangler의 표준 OAuth 흐름을 사용하며, Global API Key가 필요 없습니다. 대신 API 토큰을 사용하는 경우 다음 권한이 필요합니다:
- Account › Workers Scripts › Edit
- Account › Cloudflare Pages › Edit
- Account › Workers AI › Read
- Account › Account Settings › Read
- User › User Details › Read (선택 사항; 이메일을 표시함)
docs/deployment.md를 참조하세요.
5. 접속(Access)
설치 프로그램이 출력하는 URL을 열고, 소유자 비밀번호를 입력한 후 채팅을 시작하세요. 모든 장치는 동일한 소유자의 것이므로 어느 기기에서든 로그인할 수 있습니다. 세션 관리는 Settings → Security에서 하세요.
비밀번호를 잊으셨나요? talorys/ 디렉토리에서 다음 명령어를 사용하세요:
npx create-talorys@latest reset-password
이 명령어는 비밀번호 시크릿을 교체하고 모든 장치에서 로그아웃시킵니다.
6. 데이터가 저장되는 위치(Where your data lives)
모든 데이터는 사용자의 Cloudflare 계정 내 단일 SQLite 기반 Durable Object(personal-agent)에 저장됩니다. Talorys는 원격 측정(telemetry), 분석(analytics), 추적 또는 광고 코드를 포함하지 않으며 개발자에게 아무것도 전송하지 않습니다.
Cloudflare는 채팅 메시지 및 각 프롬프트에 포함된 관련 메모리에 대한 Workers AI 추론을 실행하는 것을 포함하여 서비스를 제공하기 위해 데이터를 처리합니다. Cloudflare의 개인정보 보호정책과 Workers AI 약관을 검토하세요.
보안 모델 및 위협 완화: docs/security.md.
7. 무료인 것과 비용이 발생할 수 있는 것(What is free and what may cost money)
Talorys는 Cloudflare Workers Free plan에 맞게 설계되었으며, 스스로 유료 기능을 활성화하지 않습니다. 하지만 '무제한 무료'는 아닙니다.
- 무료 플랜은 계정 수준의 할당량(요청, Durable Object 사용량, 일일 Workers AI Neuron 할당)을 가집니다. 이 할당량은 Cloudflare에 의해 설정되며 변경될 수 있습니다.
- AI 할당량이 소진되면 채팅창에 명확한 메시지가 표시되고 일일 초기화 후에 재개됩니다. 다른 모든 기능은 정상 작동하며 데이터는 건드려지지 않습니다.
- 계정이 유료 플랜인 경우, 포함된 양을 초과하는 사용량은 Cloudflare가 해당 플랜에 따라 청구합니다.
내장 가드레일(Settings → AI에서 조정 가능): 최대 출력 토큰 수, 최대 컨텍스트 토큰 수(이전 기록은 요약됨), 요청당 최대 도구 호출 및 추론 단계 수, 일일 최대 AI 요청 횟수, 일일 최대 예약 AI 실행 횟수. 간단한 알림과 작업 요약본은 AI를 사용하지 않습니다. 사용량 패널에는 로컬 추정치가 표시되며 정확한 Neuron 사용량을 확인하려면 Cloudflare 대시보드 링크를 이용하세요.
8. 로컬 개발
요구 사항: Node.js 20.18 이상.
git clone https://github.com/rociiu/talorys.git
cd talorys
npm install
...
npm run dev는 에이전트 워커(wrangler dev, 포트 8787), 서비스 바인딩을 갖춘 페이지 함수 프록시(wrangler pages dev, 포트 8788), 그리고 Vite UI(http://localhost:5173)를 하나의 터미널에서 시작합니다. 이 명령어는 로컬 비밀번호가 포함된 apps/agent/.dev.vars 파일을 생성하며 (talorys-dev-password, TALORYS_DEV_PASSWORD로 덮어쓸 수 있음), 결정론적 모의 AI 제공업체를 사용하므로 Cloudflare 로그인이 필요 없습니다. 상태는 .wrangler/state에 유지됩니다.
다른 스크립트: npm run build, npm test, npm run test:e2e, npm run test:pack, npm run typecheck, npm run lint. 자세한 내용은 docs/development.md를 참조하세요.
9. 데이터 백업
Settings → Privacy → Download backup을 사용하면 대화 기록, 메모리, 작업, 노트, 프로젝트, 설정 및 자동화(세션 또는 자격 증명은 포함하지 않음)가 포함된 talorys-backup.json 파일이 생성됩니다. Import 기능은 파일을 검증하고 하나의 트랜잭션으로 병합합니다. 동일한 백업을 두 번 가져와도 무해합니다.
10. 업데이트
talorys/ 디렉토리에서:
npx create-talorys@latest update
이것은 최신 Worker와 프런트엔드를 같은 리소스에 재배포합니다. Durable Object 네임스페이스는 절대 재생성되지 않으며 (마이그레이션은 append-only 방식), 소유자 비밀번호와 세션은 유지되고, 스키마 마이그레이션은 첫 요청 시 자동으로 트랜잭션 방식으로 실행됩니다. 또한 status와 doctor도 사용할 수 있습니다.
11. 문제 해결 (Troubleshooting)
| 문제 (Problem) | 해결 방법 (Fix) |
|---|
| 설치 프로그램이 중간에 중단됨 (Installer stopped midway) | 동일한 명령을 다시 실행하면 재개됩니다. |
| ... | |
npx create-talorys@latest doctor가 모든 것을 자동으로 확인합니다. 자세한 내용은 docs/troubleshooting.md를 참조하세요.
리포지토리 레이아웃 (Repository layout)
apps/agent Private Worker: Hono API, TalorysAgent, tools, SQLite 저장소(repositories)
apps/web React + Vite 앱, 페이지 함수 (Pages Function) (functions/api/[[path]].ts)
packages/shared Zod 스키마, 타입, 반복/DST 로직, 비밀번호 해싱
...
라이선스 (License)
MIT
