Javis OS
Your self-hosted AI agent with a swappable brain, and a Second Brain that gets smarter every day.
Run it on your laptop or a small VPS. Talk to it by voice. Plug in Claude, ChatGPT, Grok, Gemini or any of 14 providers, keep every tool when you switch, and let it work in the background while you sleep.
🇬🇧 English · 🇻🇳 Tiếng Việt · 🇨🇳 简体中文 · 🇪🇸 Español · 🇯🇵 日本語 · 🇮🇳 हिन्दी · 🇧🇷 Português · 🇰🇷 한국어 · 🇷🇺 Русский · 🇩🇪 Deutsch · 🇫🇷 Français · 🇮🇩 Bahasa Indonesia · 🌍 Help translate
Quick start · Why Javis · Brains · Features · Install · Docs · Support
⚡ 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:
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.
[!NOTE] 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 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
💡 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.
🧠 14 brains, one toolkit
Pick the brain on the Models page and change it whenever you like. Javis supports 14 providers today.
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.
[!WARNING] Read this before letting a subscription run background work. Anthropic scopes Claude Pro/Max 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 all fall outside that scope, and accounts have been suspended over it. Javis never reads your login token: it runs the real
claudebinary, 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. Seeserver/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.
- Agents and workflows: specialist assistants with their own memory, chained into multi-step workflows with verification.
- Chatbots: put an agent in front of your customers on its own Telegram, Slack, WhatsApp, Lark or Zalo bot, with a 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 indashboard/i18n/. - Second Brain: a markdown vault in
brains/<brain name>/.
🚀 Installation
[!IMPORTANT] 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.
🛒 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.comand point an A record at the VPS IP.
Wait 1-3 minutes for the certificate, then open https://<DOMAIN_NAME>.
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.
🛒 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.
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). Start at login: ./bin/javis-autostart.sh install. Details: bin/README.md.
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. Start at login: javis-autostart.bat install (remove: uninstall).
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.ymlagain as a second stack and fill in those three fields. - Self-managed VPS: run the shared proxy
docker-compose.proxy.ymlonce for the whole machine, then give each instance its own folder withdocker-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 6 groups. Every page has a guide in docs/en/.
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.
⚙️ 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.
🔐 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,
Securecookies 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=falseto 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
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
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
- Brains: Claude Code and the Claude Agent SDK (Anthropic), Codex CLI (OpenAI), Grok Build (xAI), Antigravity (Google), plus the APIs of OpenRouter, OpenAI, Google Gemini, Anthropic, Groq and Ollama.
- Tool standard: Model Context Protocol. The whole Javis connection store runs on it.
- The Second Brain and digital Bullet Journal patterns.
📄 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.