🧠 Javis OS

Javis OS không phải một chatbot. Nó là một lớp điều hành AI chạy trên máy/VPS của bạn, lấy CLI của nhà cung cấp AI làm "bộ não" - Claude Code CLI (gói Claude) hoặc Codex CLI (gói ChatGPT). Tận dụng chính gói subscription bạn đang trả thay vì phải mua thêm API riêng: bộ não đó có đầy đủ khả năng đọc/ghi file, gọi công cụ (MCP), chạy lệnh, dùng skill - rồi Javis gói tất cả vào một dashboard đẹp, điều khiển bằng giọng nói, kèm một Second Brain (bộ nhớ + wiki) tích luỹ tri thức theo thời gian.

Triết lý: nhà cung cấp nào có CLI dạng agent + gói subscription (Claude Code, Codex, và các CLI ra sau) thì Javis dùng được làm bộ não. Ngoài ra vẫn hỗ trợ chat thuần qua OpenRouter / OpenAI / Anthropic API.

Bạn đấu các MCP của riêng mình vào (bán hàng/POS, quảng cáo, lịch, email, ghi chú…) → Javis tự phát hiện và báo cáo kinh doanh + cuộc sống bằng số liệu thật, nói chuyện như người.

💡 Triết lý: Javis biên dịch một lần tri thức từ ghi chú thô → Wiki, rồi duy trì nó sống cùng mỗi nguồn mới. Tri thức tích luỹ, không tái phát hiện mỗi lần.

• 🎙️ Trò chuyện bằng giọng nói rảnh tay - nói, Javis nghe và trả lời bằng giọng (Edge TTS tiếng Việt). Giữ phím Cách để bật mic.
• 🌌 Đồ thị tri thức 3D - bộ não của bạn hiện ra dưới dạng nebula 3D phản ứng theo âm thanh, các note nối nhau qua [[wikilink]].
• 💬 Phiên hội thoại - lưu / mở lại / tìm kiếm toàn văn mọi cuộc trò chuyện cũ (kể cả khi đổi máy).
• 🗂️ Quản lý tệp tin - duyệt, sửa file .md/.txt trực tiếp trong trình duyệt, tải lên/về, ngay trong brain đang chọn.
• 🧩 Skills (kiểu Hermes) - gom nhóm, tìm kiếm, bật/tắt từng skill, thêm/sửa/xoá; Javis tự xếp skill mới vào đúng nhóm.
• 🤖 Agents & Workflows - tạo trợ lý chuyên biệt + chuỗi tự động (Studio), mỗi bước một agent, có kiểm chứng.
• ♻️ Tự cải thiện - Javis tự thức theo lịch làm một nhiệm vụ cụ thể (vd: mỗi sáng tổng hợp doanh thu + soạn nháp content) rồi tự kiểm chứng.
• 📊 Dashboard số liệu - panel trái tự cập nhật chỉ số kinh doanh thật từ MCP, so sánh kỳ trước, đề xuất hành động.
• 🔌 Quản lý MCP đa-shop - đấu nhiều server cùng link khác key (vd nhiều cửa hàng POS), dùng được cho cả Claude Code lẫn model OpenRouter/OpenAI.
• 📱 Telegram bot - hỏi Javis qua điện thoại, có cả MCP khi dùng engine Claude.
• 🔄 Đa engine - Claude Code CLI (đủ MCP), ChatGPT (Codex), OpenRouter, OpenAI API, Anthropic API - đổi trong Settings.
• 🔐 An toàn khi lên VPS - tự bắt buộc đăng nhập khi chạy public, chống chiếm tài khoản, rate-limit.

⚠️ Quan trọng về bảo mật: Javis chạy Claude với toàn quyền trên máy. Khi chạy public (Docker/VPS/Hostinger), Javis tự bắt buộc đăng nhập - mở app ra là màn tạo tài khoản / đăng nhập, không ai điều khiển được khi chưa có mật khẩu.

VPS Hostinger → Docker Manager → Compose → URL → dán file Hostinger rồi Deploy:

https://raw.githubusercontent.com/blogminhquy/javis-os/main/docker-compose.hostinger.yml

Ô Environment đặt biến DOMAIN_NAME (BẮT BUỘC, để Traefik của Hostinger cấp HTTPS):

• Link miễn phí (không cần mua tên miền): DOMAIN_NAME=javis.<hostname-vps>.hstgr.cloud (hostname xem ở hPanel → VPS, vd javis.srv1782015.hstgr.cloud).
• Tên miền riêng: DOMAIN_NAME=tenmien.com + trỏ DNS A về IP VPS.

Deploy → đợi 1-3 phút Traefik cấp SSL → mở https://<DOMAIN_NAME>. (Chi tiết + xử lý sự cố: DEPLOY.md.)

Chỉ muốn chạy nhanh bằng http://<ip>:7777 (chưa cần tên miền): dùng docker-compose.yml (Cách 2).

3 việc làm 1 lần:

1. Để image GHCR ở chế độ Public: GitHub → repo → Packages → javis-os → Package settings → Visibility = Public.
2. Tạo tài khoản admin (chọn 1):
   • Khuyến nghị: thêm env JAVIS_ADMIN_USER + JAVIS_ADMIN_PASSWORD ở ô Environment → mở app đăng nhập luôn.
   • Hoặc: mở app sẽ hỏi MÃ THIẾT LẬP - trong App terminal (vào bên trong container) chạy: cat /data/state/.setup_token.
3. Đăng nhập Claude (bộ não): App terminal → claude auth login --claudeai → mở link, dán code.

# Cần Docker (chưa có?  curl -fsSL https://get.docker.com | sh)
mkdir javis && cd javis
curl -fsSLO https://raw.githubusercontent.com/blogminhquy/javis-os/main/docker-compose.yml

docker compose run --rm javis claude auth login --claudeai   # đăng nhập Claude 1 lần
docker compose up -d                                          # pull image + chạy

Mở http://<ip-vps>:7777 → màn tạo tài khoản admin (xem MÃ THIẾT LẬP trong docker compose logs javis).

git clone https://github.com/blogminhquy/javis-os.git javis && cd javis
chmod +x install.sh && ./install.sh

Script tự cài Python + Node + Claude CLI, tạo venv, đăng ký dịch vụ systemd tự chạy khi boot, in ra địa chỉ. Báo Claude chưa đăng nhập thì chạy 1 lần: claude auth login --claudeai.

1. Cài Python 3.12 (tick "Add to PATH") + Node.js LTS
2. npm install -g @anthropic-ai/claude-code  &&  claude auth login --claudeai
3. Double-click  setup.bat   (chạy hiện cửa sổ)
   hoặc           start-javis.vbs   (chạy ngầm, log ở server\javis.log)
4. Mở http://localhost:7777   ·   Dừng: stop-javis.bat

📄 Chi tiết hơn (named tunnel URL cố định, build từ source…) xem DEPLOY.md.

Mở Javis → bộ cài đặt sẽ dẫn bạn qua:

1. Tài khoản admin - đặt mật khẩu (bắt buộc khi chạy public, để chặn người lạ).
2. Đăng nhập Claude - "bộ não". 1 lần, không cần API key. Token lưu trong ~/.claude (Docker: volume riêng → không mất khi update).
3. Chọn engine + model - mặc định Claude Code CLI (đủ MCP). Có thể đổi sang OpenRouter / OpenAI / ChatGPT / Anthropic API trong Models.
4. Đấu MCP (tuỳ chọn) - vào MCP, thêm server (POS, Ads…) bằng URL + key. Javis sẽ báo cáo số liệu thật từ đó.

📚 Tài liệu chi tiết: xem thư mục docs/ - hướng dẫn từng chức năng (mở ở đâu, bấm gì, dùng thế nào). Bảng dưới là bản đồ nhanh; cột Chi tiết dẫn tới trang hướng dẫn tương ứng.

Dashboard có thanh điều hướng bên trái:

Mục lục đầy đủ (17 trang): docs/README.md - gồm thêm Phiên hội thoại, Second Brain: bộ nhớ / Wiki / INGEST, Thương hiệu & tên miền riêng, Cấu hình .env.

• Hỏi số liệu: "Doanh thu hôm nay thế nào? So với hôm qua?" → Javis gọi MCP, trả số thật + đề xuất.
• Tiêu hoá tri thức (INGEST): thả file/ghi chú vào → Javis tóm tắt, rút insight, viết vào Wiki, gợi ý task.
• Tự cải thiện: vào Tự cải thiện → chọn "Tự định nghĩa" → mô tả nhiệm vụ (vd "mỗi sáng tổng hợp bán hàng hôm qua, tìm hàng bán chậm, soạn 1 caption đẩy hàng vào Projects") → bật chạy nền.
• Giọng nói: bấm mic (hoặc bật rảnh tay) → nói → Javis trả lời bằng giọng. Esc để ngắt.

Mọi dòng để trống vẫn chạy được. Sao chép env.example → .env (file mẫu cố ý KHÔNG có dấu chấm đầu để Docker Manager của Hostinger không tự nhập nó vào ô Environment).

• Khi chạy public, bắt buộc đăng nhập trước khi dùng bất kỳ chức năng nào (Claude full quyền).
• Tạo admin lần đầu cần MÃ THIẾT LẬP (in trong log server) hoặc admin đặt sẵn qua env → chống kẻ chỉ-có-URL chiếm tài khoản.
• Rate-limit đăng nhập (khoá tạm sau nhiều lần sai), mật khẩu ≥ 8 ký tự, cookie secure khi HTTPS, session hết hạn 30 ngày.
• Truy cập từ xa nên qua HTTPS (Hostinger *.hstgr.cloud hoặc Cloudflare Tunnel) - đừng phơi cổng thô.

# Trên máy bạn (sau khi sửa code): đẩy lên GitHub
git add -A && git commit -m "..." && git push     # → CI tự build image mới lên GHCR

# Trên VPS: kéo bản mới
cd javis && ./update.sh          # tự pull image + restart (dữ liệu trong volume KHÔNG mất)

docker compose --profile tunnel up -d
docker compose logs tunnel | grep trycloudflare   # → URL https://xxx.trycloudflare.com

Trình duyệt (voice + 3D) ─┐
Telegram ─────────────────┤→  FastAPI (server/) ──→  Claude Code CLI (bộ não, đủ MCP/skill)
                          │                       └→  engine khác: OpenRouter/OpenAI/Codex/Anthropic
                          └→  Second Brain (markdown vault: Memory + Wiki + Sources)

• Backend: Python FastAPI (server/) - main.py, engine.py, claude_cli.py, sessions.py, self_improve.py, mcp_*, config.py.
• Frontend: HTML/CSS/JS thuần (dashboard/) - không framework, nhẹ cho VPS.
• Bộ não: Claude Code CLI cài sẵn (subprocess) → kế thừa MCP, skill, auth.
• Second Brain: vault markdown (brain/ hoặc Obsidian vault) - bộ nhớ sống + Wiki tích luỹ.

javis-os/
├── server/              # Backend FastAPI (não, engine, sessions, MCP, self-improve…)
├── dashboard/           # Frontend (voice, đồ thị 3D, console, studio)
├── Brain Default/       # Brain mẫu (agents/workflows/wiki - dữ liệu cá nhân được .gitignore)
├── Dockerfile           # Image: python + Node + Claude CLI
├── docker-compose.yml   # Production (pull image GHCR) - VPS thường, vào bằng http://<ip>:7777
├── docker-compose.hostinger.yml  # Cho Hostinger: tên miền + HTTPS qua Traefik (đặt DOMAIN_NAME)
├── docker-compose.https.yml      # Auto-HTTPS bằng Caddy cho VPS thường (kèm file trên)
├── install.sh           # Cài native Linux/macOS
├── update.sh            # Cập nhật trên VPS
├── docs/                # Hướng dẫn sử dụng chi tiết từng chức năng (17 trang + mục lục)
├── DEPLOY.md            # Hướng dẫn deploy chi tiết
└── CLAUDE.md            # "System prompt" + quy ước cho AI agent

• Bộ não: Claude Code (Anthropic).
• Kiến trúc agent & UI: học hỏi từ Hermes Agent (Nous Research) - sessions, skill management, packaging, self-improvement.
• Pattern Second Brain + Bullet Journal số hoá.