How to use vibeOS

vibeOS (vibeos.sh) is Aleksey Bykhun's AI-native browser desktop: a real Linux virtual machine in your browser tab, a window manager, and an agent that edits the system and writes dock apps.

This guide is about that project — not Kaan Senol's VibeOS (a QEMU hobby aarch64 OS), not unrelated "VibeOS Cloud" or startup hits, and not Steve Sanderson's hallucinated-UI demo. If you're curious about the name, read Is vibeOS real?.

Open vibeOS in your browser → is the fastest way to try it, no install.

Quick start (browser)

1. Open vibeos.sh/app in a modern Chromium browser (Chrome, Edge, Arc, Brave, etc.).
2. Wait until the menu bar says the machine is ready (Alpine Linux boots inside WebAssembly).
3. Connect a model: either log in with ChatGPT for Codex, or paste an Anthropic/OpenAI API key when prompted.
4. Use the built-in chat to ask for apps, theme changes, packages on Debian, or shell work — or open Settings for Terminal, Browser, and Workspace.

If you want your apps and chat to persist, go to Settings › Workspace › Save to a folder... (which uses the Chromium File System Access API). That saves them on your disk across reloads. Without a folder, the session uses private browser storage.

If you want to bring your own agent, Settings › Capabilities prints an npx vibeos-mcp command that lets Claude Code, Cursor, or other MCP clients drive the same desktop. There's more on that in Computer use for AI agents.

What you are running

• Host: your browser tab on vibeos.sh (or your own server).
• Guest: x86 Linux via v86, running BusyBox, Alpine, or Debian images.
• Desktop: menu bar, dock, windows; system source under system/ in the workspace; apps as // @title JavaScript modules.

For more on the concept: The AI operating system for Codex & ChatGPT agents. For the browser OS angle: Linux in the browser.

Self-host with Docker (optional)

The image is self-contained: the desktop, both disk images, the guest's networking and the agent relay, all served from the container. Nothing leaves the box — there is a check that fails if any request does, websockets included.

docker run -p 127.0.0.1:3000:3000 ghcr.io/caffeinum/vibeos
# open http://localhost:3000/app

The 127.0.0.1: is load-bearing, not decoration. Origin and Host checks stop a page you merely visit from reaching the container, but they constrain browsers and not raw clients, and there is no authenticated ingress — so publishing the port beyond loopback is unsupported. No API key is needed or used by the server: you paste yours into the desktop and the browser calls your provider directly.

When pairing vibeos-mcp against a container, use the --relay URL the desktop prints — the package default points at vibeos.sh's relay.

Develop from source (this landing repo + desktop)

Landing site (what you're reading):

git clone https://github.com/caffeinum/vibeos-landing.git
cd vibeos-landing
bun install && bun dev

Open http://localhost:3000 - /app serves the static desktop from public/app.

Full vibeOS source (desktop + container): clone caffeinum/vibeOS and follow its README for bun dev / docker build. The open-source mirror of the browser build lives under web/ in that repo.

Related guides

Open vibeOS →