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.
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:
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.
[!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 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
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.
🧠 14 brains, one toolkit
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.
[!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 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.
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 in dashboard/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:
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>.
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).
# 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.
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.
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.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.
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/.
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.
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.
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.
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.
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
Javis Os कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
क्या Javis Os के लिए API key चाहिए?
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।