BOS is an agentic 'BrowserOS' that has the ability to modify itself.
Why does BOS exist? There are several good AI Agent systems out there like, Hermes Agent, AgentZero, each having their own strengths and weaknesses wrt. to what I personally was looking for.
This includes integrations, some configuration options I wanted, or some other capability I wanted. I could of course just create a fork and make the modifications myself, but I don't want the hassle of maintaining a codebase that I don't have control over.
What I really wanted, was to have the ability to modify the system from within the system itself without having to write a single line of code.
BrowserOS (BOS) has a desktop, draggable windows, a dock, and a built-in AI assistant that can operate the OS, manage files, browse the web, and install apps — just like you'd expect. What it isn't supposed to do is modify its own source code, live, on a branch you can preview before merging. But it does that too.
Clone it, run one command, and in a couple of minutes you'll have your own self-improving desktop with an assistant that can talk to you, show you its face, and build new apps and skills for itself on request.
- A real desktop, not a demo — windows, a dock, Files, Settings, and a growing set of built-in apps.
- An assistant that can act, not just chat — it browses the web, edits files, runs commands, and delegates to sub-agents for bigger jobs.
- Self-modifying, safely — the assistant writes and previews BOS's own code on an isolated branch before anything touches your live instance.
- A Marketplace, not a plugin folder — add apps, assistant skills, and spec templates from any git repo with one URL.
- Talk to it, see it — voice conversations with an optional animated avatar, not just a text box.
- Bring your own AI — Anthropic, OpenAI, a local model, and either Claude Code or OpenCode as the coding backend — your keys, your choice.
BOS has a built-in Marketplace app that lets you extend the OS with apps, assistant skills, and spec templates published in external git repositories. Just paste a URL and BOS handles the rest.
Key features:
- Three item types — install sandboxed apps (appear on the desktop instantly), skills (available to the assistant immediately), or adopt spec templates into your own Build Studio workflow.
- Multi-format support — BOS automatically detects the format when you add a URL. It supports BOS-native marketplaces (e.g. vaaale/bos-marketplace), Anthropic agent-skills repos (e.g. anthropics/skills), and Claude Code skill repos (e.g. ericgandrade/claude-superskills). No manual configuration needed.
- Search and filter — a live filter narrows items across all registered marketplaces by name, description, or tag.
- Installed badges — items you've already installed are highlighted so you never lose track of what's in your OS.
- Sync and remove — pull the latest from any marketplace with one click, or remove a source entirely without affecting what you've already installed.
To get started, open the Marketplace app and add any of these URLs:
| Marketplace | URL |
|---|---|
| BOS Marketplace | https://github.com/vaaale/bos-marketplace.git |
| Anthropic Agent Skills | https://github.com/anthropics/skills.git |
| Claude Superskills | https://github.com/ericgandrade/claude-superskills.git |
→ Full tutorial: Using the Marketplace
There are two ways to run BOS:
| Mode | When to use |
|---|---|
| Dev mode (single user) | Local development, trying BOS out, contributing |
| Docker Compose (multi-user) | Shared team instance, production, or self-hosted deployment |
- Node.js 20+ and npm
- Git
- An API key for an AI provider (Anthropic, OpenAI, or a local OpenAI-compatible server)
git clone <repo-url>cd browseros
npm installcp .env.example .env.local
# Optional: seed a default API key so the wizard is pre-filled:# ANTHROPIC_API_KEY=sk-ant-...No env vars are required — everything including the API key is configurable at runtime through the first-run wizard or Settings → AI Provider. Env vars are only a convenience to pre-seed the defaults.
With the Supervisor (recommended — enables live version control, branch previews, and safe self-modification):
BOS_BASE_DEV=1 BOS_PORT_BASE=3000 BOS_PUBLIC_PORT=8090 npm run supervisorWithout the Supervisor (plain Next.js dev server, no self-modification):
npm run devOn first launch a guided setup wizard walks you through:
- AI Provider — which model powers the assistant (Anthropic / OpenAI / local), with a live model list
- Dev Harness — the autonomous coder the assistant delegates to (Claude Code or OpenCode)
- Data Isolation — how preview data is isolated from live data during self-modification
- Git Repos — where your BOS source, spec store, and personal app repo live (sensible defaults, all editable)
- Marketplace — which app marketplaces to add out of the box
- A live progress screen while BOS provisions itself
Every step is optional — skip the wizard entirely and configure everything from Settings at any time.
BOS supports any OpenAI-compatible provider. Configure in Settings → AI Provider at runtime, or seed defaults in .env.local:
| Provider | Key to set |
|---|---|
| Anthropic | ANTHROPIC_API_KEY=sk-ant-... |
| OpenAI | Configure base URL and key in Settings |
| OpenAI Responses | Configure base URL and key in Settings |
| Local (vLLM, Ollama, etc.) | ANTHROPIC_BASE_URL=http://... and ANTHROPIC_API_KEY=local |
(Not stable yet)
For multi-user deployments, BOS ships a bastion service that handles authentication, spawns per-user BOS containers dynamically, and proxies traffic to them.
Browser → bastion:80 → bos-{username}:8090
Each user gets their own isolated source tree, data directory, and node_modules volume.
- Docker Engine 24+ and Docker Compose
- Git
docker build -t browseros:latest .cp .env.example .env
# Required — generate a secret:echo"JWT_SECRET=$(openssl rand -hex 32)">> .envbos-net is an external network so it is never recreated by compose (which would break running user containers). Create it once:
docker network create bos-netdocker compose up -dVisit http://localhost — you will be presented with a login page.
Generate a bcrypt hash inside the running bastion container, then write users.yml:
# Step 1: generate the hash (the bastion already has bcryptjs installed)
HASH=$(docker compose exec bastion node -e "const b=require('bcryptjs'); console.log(b.hashSync('changeme', 12))")# Step 2: write users.yml into the bastion data volume
docker compose exec bastion sh -c "printf 'users:\n admin:\n passwordHash: %s\n admin: true\n' '$HASH' > /data/users.yml"Then log in at http://localhost with admin / changeme and change your password from the account page (/app/account).
| Provider | Config |
|---|---|
| Simple (default) | Users defined in /data/users.yml inside bastion. Bcrypt passwords, hot-reloaded. |
| Keycloak | Set AUTH_PROVIDER=keycloak and KEYCLOAK_* vars. Use the Keycloak compose override. |
# Start with a local Keycloak (bundled bos realm pre-imported):
docker compose -f docker-compose.yml -f docker-compose.keycloak.yml up -dSee docs/dev/deployment.md for the full deployment guide including Keycloak setup, volume layout, and re-provisioning.
For the AI assistant to write and preview code changes, it needs a developer harness — an autonomous coder it can delegate to. Pick either Claude Code or OpenCode in Settings → Dev Harness, then authenticate it however suits you: an interactive credential-file login, a plain API key, AWS Bedrock, Google Vertex AI, or (for Claude Code) a dedicated OAuth token via claude setup-token that won't conflict with your own local CLI session.
Claude Code, if you want it, installs with:
npm install -g @anthropic-ai/claude-codeWithout a harness configured, everything else in BOS still works — you just lose self-modification.
- docs/usage/ — using BOS (the desktop, apps, assistant, memory, settings)
- docs/dev/ — extending and modifying BOS (architecture, API reference, recipes)
- docs/dev/deployment.md — full Docker multi-user deployment guide
The in-OS Docs app renders these trees inside BOS itself.
npm run dev # plain Next.js (port 3000)
npm run supervisor # with Supervisor (port 8090, enables self-modification)
npx tsc --noEmit # typecheck
npm run lint # lint
npm run test:e2e # Playwright e2e testsBOS follows a spec-first workflow: features are specified in Build Studio before being implemented. See specs/bos-system-specs/ and docs/dev/architecture-overview.md.
BOS builds itself in the open — most new features start as a spec written in Build Studio, often by BOS's own assistant. Bug reports, feature specs, and pull requests are all welcome via GitHub Issues.
Licensed under Attribution-NonCommercial 2.0.