Getting Started
What VibeAI OS looks like day one, and how to install it.
VibeAI OS is a self-hosted AI operating system: agents with persistent memory, document-grounded projects, cost-managed model access, and channels (web, Telegram, voice, CLI) — all on a server you (or we) control. Most of what you’ll do day to day happens in the web dashboard, not the shell.
Logging in
After install, the dashboard is at https://aios.<yourdomain> (server
installs) or http://localhost:9200 (local installs) — sign in with the
admin user and the password you chose during provisioning.
The sidebar, section by section
The left sidebar is grouped into five sections. Every page underneath is backed by a real API — nothing in the dashboard is a mockup.
Dashboard, Chat, Console, Vibe Code, Projects, Sessions — the surfaces you use to actually talk to and work with agents.
Operate
- Dashboard — the landing page: gateway state, stat tiles, recent sessions, and a query bar wired to live agent chat.
- Chat & Console — message-bubble chat or a terminal-style REPL, both against the same agent socket.
- Vibe Code — the full coding workstation: real Claude Code CLI sessions, multiple tabs, task tracking, project management, skill/agent creation.
- Projects — document folders agents retrieve from and cite when answering.
- Sessions — every conversation transcript, across every channel.
Intelligence
- Analytics & Budgets — spend ledger, per-model breakdowns, and opt-in budget enforcement.
- Models — switch the active provider/model with a click instead of a config edit.
- Reviews — the meta-reviewer’s cold-context corrections log.
Automate
- Cron — scheduled agent jobs.
- Skills & Hooks — reusable verified skills and lifecycle hooks.
- Plugins — installable dashboard/agent extensions.
Connect
- Channels — per-agent Telegram bots and other message channels.
- MCP — external MCP servers an agent can call tools on.
- Webhooks — inbound HTTP triggers into an agent.
- Access — auth, remote access, and per-surface gates.
System
- Clients — fleet/tenant view (mothership installs only).
- Agents — agent profiles, gateway state, credentials.
- Config — the raw
config.yamleditor. - Keys — the encrypted secrets vault: provider API keys and tokens, managed from the dashboard.
- System — CPU/memory/disk and service state.
- Logs — live tail of dashboard/gateway logs.
- Docs — this manual.
Every nav link lands on real, working data — if a page ever looks bare, it’s because that feature genuinely has nothing configured yet (no projects created, no cron jobs scheduled), not because it’s a stub.
Installing
The dashboard above is what you get after running one of these installers.
Server install (Ubuntu)
On a bare Ubuntu server, from an unpacked release (or repo checkout):
APEX_DOMAIN=yourdomain.com ADMIN_PASSWORD=choose-one \
./deploy/provision.sh --with-chroma
This is idempotent — re-running never overwrites existing config,
credentials, or data. It installs packages, binaries, systemd units, nginx
sites (aios.<apex> dashboard, vibe-ui.<apex> panel), creates the
gateway password, and scaffolds /root/.aios.
Local install (your own machine, incl. macOS)
For running VibeAI OS on a laptop/workstation instead of a shared server — no nginx, no auth proxy, no license gate, just your own account:
git clone <this repo> && cd vibeai-os
./deploy/provision-macos.sh --dry-run # see the plan first, changes nothing
./deploy/provision-macos.sh # builds aios + aios-dashboard from
# source and installs to ~/.local/bin
Installs Rust via rustup if missing, builds native binaries for your
machine’s architecture (no cross-compilation), and scaffolds ~/.aios.
Add --with-launchd to have the dashboard/gateway start at login and
restart on crash; without it, run them manually (aios chat,
aios-dashboard --port 9200). --skip-build reuses an existing release
build for a quick re-provision.
First five minutes after provisioning
https://aios.<apex> (server installs; user admin, your
ADMIN_PASSWORD) or http://localhost:9200 (local installs). A fresh
install shows the onboarding wall instead of the app: create your
account, answer a few about-you fields, then pick a provider and
paste its API key (or use a detected local runtime — Ollama /
LM Studio — with no key at all). The key is stored in the encrypted
secrets vault, and the server refuses API traffic
(409) until onboarding is complete — the wall isn’t skippable.
aios setup — walks through provider selection (all of DeepSeek,
Anthropic, OpenAI, Gemini, OpenRouter, Groq, Mistral, xAI, Ollama, or
a custom endpoint), model choice, and your API key, and writes them
to config.yaml and the secrets vault. aios setup -y accepts
defaults non-interactively (DeepSeek v4 Flash, no key prompt — add
one later on the Keys page or with aios secrets set).
aios -p "hello" from the shell — you should get an answer streamed
through the full harness. Keys added through the dashboard are read
from the vault on the next request; no service restart is needed for
a key change.
What a running install looks like on disk
| Piece | What it is | Where |
|---|---|---|
aios | CLI + agent runtime + gateway | /usr/local/bin/aios |
aios-dashboard | web API + this UI | :9200, behind the auth proxy |
aios-gateway | Telegram/channel daemon | systemd aios-gateway[@profile] |
| AIOS home | ALL state (config, sessions, memory, projects, encrypted secrets.db) | /root/.aios |
| Vault key | decrypts secrets.db | owner-read-only .kek in the AIOS home (every platform) |
| Auth proxies | login gates per subdomain | vibe-ui-auth, aios-dashboard-auth |
Verifying an install
./deploy/e2e.sh yourdomain.com runs the 18-check acceptance suite —
services, APIs, gateways, a real agent turn, memory persistence, budget
enforcement, and the project lifecycle. Everything green = healthy box.