⚡ Quick start
The easy way: let your own AI install it. Give this repo link to Claude Code or Codex on your machine and say “install Javis OS for me”. It only needs to run one command:
| Machine |
One command installs everything |
| Linux / macOS |
git clone https://github.com/blogminhquy/javis-os.git javis && cd javis && chmod +x install.sh && ./install.sh |
| Windows |
git clone https://github.com/blogminhquy/javis-os.git javis; cd javis; powershell -ExecutionPolicy Bypass -File install.ps1 |
| Docker |
curl -fsSLO https://raw.githubusercontent.com/blogminhquy/javis-os/main/docker-compose.yml && docker compose up -d |
Then open http://localhost:7777. The installer sets up Python, the four subscription CLI brains (claude, codex, agy, grok) and a .env, then starts the server. You sign in to each brain on the Models page of the dashboard, no more typing commands.
Installed an extra CLI after Javis was already running? Restart Javis. A running process keeps the PATH it started with, so it cannot see a CLI installed later.
🤔 Why Javis?
Javis OS is not a chatbot. It is a self-hosted agentic AI that runs on your own machine or VPS: it reads and writes files, calls tools over MCP, runs skills, queues background work and schedules itself. All of that sits behind a voice-controlled dashboard with a Second Brain (memory + wiki) that accumulates knowledge over time.
The lock-in nobody warns you about
Pick one AI app and use it every day for a year. Then look at what has piled up inside it:
- Hundreds of conversations, holding the decisions and context you worked out along the way.
- Memory of who you are, how you work and what your business sells.
- Custom instructions, assistants and projects: know-how you spent hours tuning.
- Automations and agents that only run on that one platform.
All of it sits on the vendor’s servers, in the vendor’s format. Then a better model ships somewhere else. You can try it, but you cannot bring your work along: the new app knows nothing about you, your instructions do not carry over, and your history stays behind. Exports, where they exist, are usually a dump of chat logs, not memory another tool can use.
So you stay. Not because the old model is still the best, but because leaving means starting from zero. And when the vendor raises prices, tightens limits, retires a model or locks your account, there is no plan B.
Javis turns it around: rent the model, own the brain
In Javis the model is a part you can swap. Everything you build up lives with you, as files you can open:
| What you build up |
Where it lives |
Format |
| Conversations |
conversations.db on your own machine or VPS, one store whichever brain answered |
SQLite, full-text searchable |
| Memory about you |
memory/ in your brain: MEMORY.md plus one file per fact |
Markdown |
| Knowledge |
the Wiki and Sources folders of your brain |
Markdown, Obsidian-compatible |
| Skills |
skills/<name>/SKILL.md |
Markdown |
| Agents and workflows |
agents/*.md, workflows/*.md |
Markdown with front matter |
| Loops and reminders |
Javis/loops/*.md, Javis/reminders.json |
Markdown, JSON |
What that buys you:
- A new model comes out? Switch on the Models page and keep going. It reads the same memory, runs the same skills, agents and workflows, and calls the same connections through the MCP Hub. Nothing to migrate, nothing to rebuild.
- Use several brains at once. A strong model for the conversation, a cheaper one for background work, a local Ollama model for private notes, all working on the same brain.
- Readable without Javis. Your brain is a folder of markdown. Open it in Obsidian or any editor. If Javis disappeared tomorrow, your knowledge would still be there, in plain text.
- Versioned and portable. Every learning pass is a git commit you can undo in one tap, and the whole brain can sync to your own private GitHub repo, shared between your laptop and your VPS.
- Your data stays on your hardware. There is no Javis cloud in between. A request goes only to the model provider you picked for it, and with a local Ollama model it never leaves your machine.
Javis next to an ordinary chatbot
|
An ordinary chatbot |
Javis OS |
| Brain |
Locked to one model, one stateless API call per message |
Swappable: 14 providers, each with the full set of tools, MCP, skills and sessions, including models running on your own machine through Ollama |
| Memory |
Forgets after every session |
A living Second Brain that remembers you and thickens with every conversation |
| Data |
Made up, or absent |
Real numbers from the connections you wire in (sales, ads, calendar, email, messaging) |
| Work |
Answers, then waits |
Background loops, reminders and an AI-run task queue that report back to you |
| Interface |
A chat box |
Dashboard + knowledge graph + hands-free voice + Telegram, Slack, WhatsApp, Zalo + a CLI |
| Your work |
Stays on the vendor’s servers, in the vendor’s format |
Plain files on your machine: history, memory, skills, agents and workflows carry over to any new model |
| Deployment |
Someone else’s cloud |
Self-hosted: one-click Hostinger, Docker, or any VPS |
💡 The philosophy: capability lives in Javis, not in the model. Every brain gets the same toolbox through one shared connection hub (the MCP Hub). Switching from Claude to Gemini costs you nothing except shell access, which only the CLI engines have.
Pick the brain on the Models page and change it whenever you like. Javis supports 14 providers today.
| Brain |
How you pay |
Shell, web, sub-agents |
| Claude Code |
Your Claude plan, or an Anthropic API key |
✅ |
| ChatGPT (via Codex) |
Your ChatGPT plan |
✅ |
| Grok Build |
Your SuperGrok or X Premium+ plan |
✅ |
| Antigravity CLI |
Your Google plan (same lineup as the Antigravity IDE, Claude included) |
Shell ✅ |
| OpenRouter |
API key (hundreds of models behind one key) |
via Javis tools |
| OpenAI API · Anthropic API · Google Gemini · Groq · DeepSeek |
API key |
via Javis tools |
| Ollama Cloud · Ollama on this machine |
API key, or free on your own hardware |
via Javis tools |
| Any OpenAI-compatible or Anthropic-compatible endpoint |
Whatever that endpoint or reseller needs |
via Javis tools |
Every brain can call your connected MCP servers, read and write the brain, run skills, queue Kanban work, and create agents, workflows, loops and reminders. The CLI engines additionally run shell commands, fetch and search the web, and spawn parallel sub-agents.
A note before letting a subscription run background work. Anthropic scopes Claude Pro/Ultra to ordinary personal use of Claude Code. Continuous background execution (loops, reminders, Kanban jobs, chatbots), running on a VPS, or several people sharing one account fall outside that scope, so there is a risk of the account being locked, although Javis has no reported case so far. If it happens to you, please tell the developer through Issues. Javis never reads your login token: it runs the real claude binary, but that does not make round-the-clock background use legitimate. To be safe, set Claude Code to run on an API key on the Models page, or point the background-work model at another provider. The same caution applies to the xAI plan. See server/claude_auth.py.
✨ Features
🗣️ Talk to it
- Hands-free voice: speak, Javis listens and answers out loud (Edge TTS free by default, or OpenAI and ElevenLabs).
- Chat sessions you can save, reopen and full-text search. Long sessions are compacted into summaries instead of being cut off.
- Telegram, Slack, WhatsApp, Zalo, a CLI and a web dashboard, all talking to the same Javis (setup for Slack and WhatsApp).
- Any language: Javis replies in the language you write in. The interface ships in English and Vietnamese.
🧠 Remember everything
- Second Brain: a markdown vault (Obsidian-compatible) with long-term memory, a Wiki and raw Sources.
- Knowledge graph of your notes joined by
[[wikilink]], on a light canvas that works offline.
- Self-learning: after each conversation Javis distils memories, wiki knowledge and skills. Every learning pass is a git commit, so it is one-tap undoable.
- Back up to GitHub: two-way sync of every brain to a private repo, shared between your laptop and your VPS.
|
⚙️ Work while you sleep
- Tasks (Kanban): hand over a goal in plain words. The AI writes the spec, picks a worker, runs it in the background and only calls you on exceptions.
- Loops and reminders: background jobs on an interval, a clock time or a cron expression, each checking its own work.
- Coworkers (the Partners page): give each AI coworker a role, its own model, prompt and skills, and switch on Auto so it keeps working without you.
- Teams: put several coworkers in one team chat. A leader hands out the work, members answer each other, and you can share a whole team as one file.
- Agents and workflows: specialist assistants with their own memory, chained into multi-step workflows with verification.
- Multi-channel chatbots: put a coworker in front of your customers on WhatsApp, Messenger, Instagram, Telegram, Slack, Lark, Threads, Zalo and Zalo OA, with one shared inbox you can take over.
🔌 Connect anything
- MCP connection store with several accounts per service and three permission levels that Javis hard-enforces.
- Skills and plugins: drop in a folder to add know-how (skill) or a native Python tool (plugin) for every engine.
- Image generation on the ChatGPT plan you are already signed in to.
- Usage tracking: tokens and cost per day, per provider, split between what you typed and what ran on its own.
|
🏗️ How it works
flowchart LR
subgraph You
W[Web dashboard<br>voice + graph]
T[Telegram]
C[Javis CLI]
Z[Zalo / bot channels]
end
subgraph Javis["Javis OS (FastAPI, self-hosted)"]
R[Engine router]
H[MCP Hub<br>shared toolbox]
B[(Second Brain<br>Memory + Wiki + Sources)]
Q[Background work<br>Tasks, loops, reminders]
end
subgraph Brains
S[Subscription CLIs<br>Claude Code, Codex, Grok, Antigravity]
A[API engines<br>OpenRouter, OpenAI, Anthropic, Gemini, Groq, DeepSeek, Ollama]
end
W & T & C & Z --> R
R --> S & A
S & A --> H
H --> B
H --> M[Your MCP servers<br>sales, ads, calendar, email...]
Q --> R
- Backend: Python FastAPI in
server/: engines (claude_sdk_engine.py, claude_cli.py, antigravity_cli.py, engine.py, aux_engine.py), tools (mcp_hub.py, mcp_store.py, plugins_host.py), background work (tasks.py, self_improve.py, reminders.py, learn.py), language and locale (lang.py, lang_registry.py, localefmt.py).
- Frontend: plain HTML/CSS/JS in
dashboard/. No framework and no build step, so it stays light on a small VPS. Interface strings live in dashboard/i18n/.
- Second Brain: a markdown vault in
brains/<brain name>/.
🚀 Installation
Javis runs an AI brain with full rights on the machine. When it runs publicly (Docker, VPS, Hostinger), Javis forces login by itself: opening the app shows a create-account or sign-in screen, and nobody can drive it without a password.
💻 On your own Windows or Mac computer? Download the installer and open it like any app: JavisOS-Setup.exe (Windows 10/11) or JavisOS-macOS.dmg (macOS 11+). It checks what is missing (Git, Python, Node, AI brains), installs it, and leaves a JAVIS OS icon to click. Steps: QUICKSTART.en.md.
Option 1: Hostinger Docker Manager (domain + HTTPS, one click)
🛒 No VPS yet? Get a Hostinger VPS here. Docker Manager comes built in, so Javis installs in one click. Once it is ready, come back to the steps below.
Hostinger VPS → Docker Manager → Compose → URL → paste the Hostinger file and press Deploy:
https://raw.githubusercontent.com/blogminhquy/javis-os/main/docker-compose.hostinger.yml
The Environment box needs only three fields: DOMAIN_NAME, JAVIS_ADMIN_USER, JAVIS_ADMIN_PASSWORD, plus an optional JAVIS_AUTO_UPDATE (set it to true and Javis updates itself daily).
Set DOMAIN_NAME so Hostinger’s Traefik issues HTTPS:
- Free link (no domain purchase):
DOMAIN_NAME=javis.<vps-hostname>.hstgr.cloud (hostname under hPanel → VPS, e.g. javis.srv1562015.hstgr.cloud).
- Your own domain:
DOMAIN_NAME=example.com and point an A record at the VPS IP.
Wait 1-3 minutes for the certificate, then open https://<DOMAIN_NAME>. No Traefik on the VPS (a plain Ubuntu 26 image)? Use the same link: the bundled javis-gateway (Caddy) issues the certificate itself when ports 80/443 are free.
Three one-time steps:
- Make the GHCR image Public: GitHub → repo → Packages →
javis-os → Package settings → Visibility = Public.
- Create the admin account: fill in
JAVIS_ADMIN_USER + JAVIS_ADMIN_PASSWORD (recommended), or open the app right after deploying and set one yourself. While no admin exists, whoever opens the link first can create it. Then turn on 2FA (Security and accounts).
- Sign in to a brain on the Models page.
Details and troubleshooting: DEPLOY.en.md.
Option 2: Docker on any VPS (no clone needed)
🛒 Need a VPS? A Hostinger VPS runs this option too.
# Docker required (don't have it? 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 # sign in to Claude once (optional)
docker compose up -d # pull the image and run
Open http://<vps-ip>:7777 and set the admin username and password right away (at least 8 characters), or preset JAVIS_ADMIN_USER + JAVIS_ADMIN_PASSWORD in the environment. Then turn on 2FA.
Remote access without a domain: docker compose --profile tunnel up -d, then docker compose logs tunnel | grep trycloudflare prints an HTTPS link.
Option 3: Linux or macOS, no Docker
git clone https://github.com/blogminhquy/javis-os.git javis && cd javis
chmod +x install.sh && ./install.sh
The script installs Python, Node and the CLI brains, creates a venv, registers a service that starts at boot, and prints the address.
🍎 macOS, open it like an app: double-click JAVIS OS.app (or Start JAVIS OS.command). Since 0.306.0 ./install.sh makes Javis start at login and open the dashboard (turn off: ./bin/javis-autostart.sh uninstall). Details: bin/README.md.
Option 4: Windows (personal machine)
git clone https://github.com/blogminhquy/javis-os.git javis; cd javis
powershell -ExecutionPolicy Bypass -File install.ps1
install.ps1 does it all in one pass: Python, venv and libraries, the four subscription CLI brains (claude, codex, agy, grok), the .env, freeing port 7777 and starting the server. It ends with a table of which brains are ready. Without winget, install Python 3.12 (tick “Add python.exe to PATH”) and Node.js LTS by hand first, then run it again.
Run with a visible window (live log): setup.bat
Run silently from then on: start-javis.vbs (log at server\javis.log)
Stop: stop-javis.bat
Dashboard: http://localhost:7777
🪟 Open it like an app: after the first run, double-click JAVIS OS.bat. The server starts in the background and the dashboard opens in its own window with its own taskbar entry. Since 0.306.0 the installer makes Javis start at login and open the dashboard (turn off: javis-autostart.bat uninstall or the button in Settings).
Several Javis instances on one VPS
Brains, settings and accounts stay fully separate per instance. Only three values differ between them: JAVIS_NAME, JAVIS_HOST_PORT, DOMAIN_NAME.
- Hostinger: deploy
docker-compose.hostinger.yml again as a second stack and fill in those three fields.
- Self-managed VPS: run the shared proxy
docker-compose.proxy.yml once for the whole machine, then give each instance its own folder with docker-compose.multi.yml. The proxy discovers new instances and requests SSL by itself.
- Native:
JAVIS_NAME=javis-shop JAVIS_PORT=7778 ./install.sh.
Step by step: DEPLOY.en.md.
🎬 First run
Open Javis and the setup wizard walks you through it, in your browser’s language:
- Admin account: required when running publicly, to keep strangers out.
- Pick a brain: sign in once with a subscription, or paste an API key. The Claude Code card has a “Runs on” switch between your signed-in plan and an Anthropic API key.
- Pick a model: switching providers later loses no features (except shell commands, which only the CLI engines have).
- Wire up connections (optional): open Connections, pick a service and paste a key or scan a QR code. Javis then reports on real numbers from it.
📖 Using Javis
The left rail groups the pages into 5 groups. Every page has a guide in docs/en/.
| Group |
Pages |
Guides |
| Brain |
Graph, Chat, Files, Self-learning |
Chat and voice · Knowledge graph · Sessions · File manager · Self-learning |
| Capabilities |
Partners (agents and workflows), Chatbot, Skills, Plugins, Terminal |
Agents and workflows · Chatbots · Customer conversations · Skills · Plugins · Terminal |
| Work |
Tasks, Scheduled |
Tasks (Kanban) · Recurring jobs and reminders |
| Connections |
Connections, Javis Store, Channels, Models |
Connections and business data · Telegram · Zalo · Models and engines |
| System |
Settings, Share links, Account |
Getting started · Security and accounts · Usage and cost · Javis CLI |
More: Second Brain: memory, Wiki and INGEST · GitHub backup · Tasks and Dataview in notes · Branding and custom domains · Troubleshooting
A few things to try
- Ask for numbers: “How is revenue today compared with yesterday?” Javis calls the right connection and answers with real figures plus suggestions.
- Digest knowledge: drop in a file or a note. Javis summarises it, extracts insight, writes it into the Wiki and proposes tasks.
- Hand over background work: Tasks → + Assign goal → “summarise this week’s sales, find slow-moving stock, draft three captions to push it”. The AI specs it, runs it and reports back.
- Schedule something: “remind me every weekday at 8:30 to check the ads budget”, in chat or on the Scheduled page.
- Use your voice: press the mic (or turn on hands-free), speak, and Javis answers out loud.
Works on your phone too: add it to the home screen and it opens like an app.
⚙️ Configuration (.env)
Every line can stay empty and Javis still runs. Copy env.example → .env and add what you need. The full list with an explanation per variable is in docs/en/16-env-configuration.md.
| Variable |
Meaning |
Default |
JAVIS_HOST |
Listen address. 127.0.0.1 = this machine only, 0.0.0.0 = public |
127.0.0.1 |
JAVIS_PORT |
Port |
7777 |
JAVIS_REQUIRE_LOGIN |
1/0 to force login on or off (default: on when bound publicly) |
(auto) |
JAVIS_ADMIN_USER / JAVIS_ADMIN_PASSWORD |
Create the admin at deploy time |
- |
JAVIS_ALLOWED_HOSTS |
Extra hostnames on the allow-list (CSRF and DNS-rebinding protection) |
localhost + your domain |
JAVIS_STATE_DIR |
Where settings, sessions and the encryption key live |
server/ (Docker: /data/state) |
BRAINS_DIR |
Parent folder holding every brain |
brains/ (Docker: /brains) |
JAVIS_ENABLE_USER_PLUGINS |
false turns your own plugins off (they run real Python inside the server) |
(on) |
TTS_VOICE / TTS_RATE |
Voice and speed for Edge TTS |
en-US-EmmaMultilingualNeural / +5% |
🔐 Security
- Login is required on a public server before any feature works, because the brain runs with full rights on the machine.
- 2FA (TOTP), login rate limiting, passwords of at least 8 characters,
Secure cookies under HTTPS, sessions that expire after 30 days.
- CSRF and DNS-rebinding protection: any write request from an unknown origin is rejected.
- Secrets are encrypted in
settings.json (API keys, OAuth tokens, bot tokens) with a per-machine key.
- Your own plugins load by default, but each one stays off until you enable it in the app; set
JAVIS_ENABLE_USER_PLUGINS=false to turn them all off.
- Connection permissions are enforced by the hub, not by the model: a read-only account cannot be used to send, pay or publish.
Found a vulnerability? Please follow SECURITY.md instead of opening a public issue.
🔄 Updating
In the app: Settings → Updates → Update now, with a progress bar and a rollback button if the new build breaks. On a VPS: cd javis && ./update.sh (pulls the new image and restarts; your data in the volumes is kept).
🩺 Troubleshooting
| Symptom |
What to do |
| The Models page says a CLI is not installed, but it is |
Restart Javis: the running process keeps the PATH from when it started. |
| Port 7777 is taken and the new build will not start |
Stop the old process first (stop-javis.bat, or kill the PID), then start again. |
| Hostinger cannot pull the image |
Set the GHCR package to Public and wait for the GitHub Action build to finish. |
| A brain says it is not signed in |
Models → that provider’s card → sign in. |
More in docs/en/17-troubleshooting.md.
📂 Repository layout
javis-os/
├── server/ # FastAPI backend: engines, connections, background work, channels, memory
├── dashboard/ # Frontend (plain JS, no build step)
│ └── i18n/ # Interface strings, one JSON file per language
├── brains/ # Every Second Brain (default: brains/Brain Default)
├── system/ # Ships with the app: bundled plugins, system skills, connection catalogue
├── docs/ # User guides (docs/en/ in English) and translations (docs/i18n/)
├── tests/ # Python + JS test suite (python tests/run.py)
├── install.sh · install.ps1 · update.sh
├── Dockerfile · docker-compose*.yml
└── CLAUDE.md # The system prompt Javis runs on
🌍 Languages
| What |
Languages today |
| Javis’s replies |
Any language: it answers in the language you write in, or one you pin in Settings |
| Dashboard and server messages |
🇬🇧 English · 🇻🇳 Tiếng Việt, per device: each browser gets its own language until you pick one |
| Connection store, plugins, a new brain’s starter files |
🇬🇧 English · 🇻🇳 Tiếng Việt |
| README and quick start |
🇬🇧 English · 🇻🇳 Tiếng Việt · 🇨🇳 简体中文 · 🇪🇸 Español · 🇯🇵 日本語 · 🇮🇳 हिन्दी · 🇧🇷 Português · 🇰🇷 한국어 · 🇷🇺 Русский · 🇩🇪 Deutsch · 🇫🇷 Français · 🇮🇩 Bahasa Indonesia |
| Full documentation |
🇬🇧 English · 🇻🇳 Tiếng Việt |
Adding a language is a data change, not a code change: one entry in server/lang_registry.py plus one dashboard/i18n/<code>.json, and optionally system/mcp-catalog.<code>.json. Anything not translated yet shows in English. See CONTRIBUTING.md if you would like to help.
🤝 Contributing
Bug reports, ideas, translations and pull requests are all welcome, in English or Vietnamese.
Please follow the Code of Conduct, and report security problems privately as described in SECURITY.md.
If Javis is useful to you, a ⭐ on the repo helps other people find it.
🙏 Credits
📄 License
Open source under the MIT License: use, modify and distribute freely, just keep the copyright notice. See LICENSE.
☕ Support Javis OS
Javis OS is free and open source, and it is still one person writing the code and paying for the test servers. If Javis helps your work or your life, a small donation buys more time for bug fixes and new features.
- 🌍 PayPal: paypal.me/quy01
- 🏦 MB Bank (Vietnam):
6636966369
- 📱 MoMo wallet (Vietnam):
0372752740
Can’t donate? Using Javis, sending feedback or opening a pull request counts as support too.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
评论