Retrieved article excerpt
Open article · Retrieved 2026-09-14T23:21:51.228307+00:00
[Amigo, the AgenticOS pet](https://github.com/vstorm-co/agenticos/blob/main/docs/assets/amigo.svg)
# AgenticOS
**One place to build, run and govern your company's AI agents.**
Self-hosted and open source — on your Postgres, in your Docker, under your
domain.
The OS in the name is a claim we make good on: [seven functions, seven mechanisms](https://github.com/vstorm-co/agenticos#the-best-agentic-os-you-can-run-yourself).
[Quick start](https://github.com/vstorm-co/agenticos#-quick-start) ·
[Screens](https://github.com/vstorm-co/agenticos#what-it-looks-like) ·
[Presentation](https://vstorm-co.github.io/agenticos/presentation/) ·
[Docs](https://github.com/vstorm-co/agenticos/blob/main/docs/index.md) ·
[Why an OS](https://github.com/vstorm-co/agenticos#the-best-agentic-os-you-can-run-yourself) ·
[Comparison](https://github.com/vstorm-co/agenticos#compared-with-the-alternatives)
[CI](https://github.com/vstorm-co/agenticos/actions/workflows/ci.yml)
[Release](https://github.com/vstorm-co/agenticos/releases)
[Coverage](https://github.com/vstorm-co/agenticos/blob/main/docs/testing.md)
[Licence](https://github.com/vstorm-co/agenticos/blob/main/LICENSE)
[Pydantic AI](https://ai.pydantic.dev)
[Stars](https://github.com/vstorm-co/agenticos/stargazers)
**English** ·
[Polski](https://github.com/vstorm-co/agenticos/blob/main/README.pl.md) ·
[Deutsch](https://github.com/vstorm-co/agenticos/blob/main/README.de.md) ·
[Español](https://github.com/vstorm-co/agenticos/blob/main/README.es.md)
---
A company ends up with agents in five places and cannot answer four questions:
**what do we run, what did it cost, what did it touch, and who said it could.**
AgenticOS is one place to build them and one set of books for all of them.
**The harness, as a product**: skills, context files — `AGENTS.md` as a page —
MCP at registry scale, automations on a schedule or a trigger, and a budget that
stops a run *before* the model call.
Below: a spreadsheet dropped into the chat, one sentence asking for charts. The
agent writes the code, runs it in a locked box, and answers.
chat-live-demo-master.mp4
[
](https://private-user-images.githubusercontent.com/111304236/644352901-9a8e0f44-781c-4f93-990d-b5b7094cc8fc.mp4?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODk0Mjg0MTAsIm5iZiI6MTc4OTQyODExMCwicGF0aCI6Ii8xMTEzMDQyMzYvNjQ0MzUyOTAxLTlhOGUwZjQ0LTc4MWMtNGY5My05OTBkLWI1YjcwOTRjYzhmYy5tcDQ_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwOTE0JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDkxNFQyMzIxNTBaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT0yYmUzYTkwYWVlNGY2OGVjYjE0MGZhN2UzZDljZTdmNzFkZTc3YTEzZGVkNTU5NGUwMjk2MmQ3MjUxOTY1M2VjJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZyZXNwb25zZS1jb250ZW50LXR5cGU9dmlkZW8lMkZtcDQifQ.ako9pNlR4ALBqxdVsQB1zB3Xg_hC5ZG5oDYjviVPP_s)
And the same console on the desktop, with company: the optional
[desktop app](https://github.com/vstorm-co/agenticos#on-the-desktop-if-you-like), its pet, and a shortcut that screenshots
straight into a new chat.
pet.mp4
[
](https://private-user-images.githubusercontent.com/111304236/648156041-b82867ae-3543-406e-a552-e3a8b61f1d10.mp4?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODk0Mjg0MTAsIm5iZiI6MTc4OTQyODExMCwicGF0aCI6Ii8xMTEzMDQyMzYvNjQ4MTU2MDQxLWI4Mjg2N2FlLTM1NDMtNDA2ZS1hNTUyLWUzYThiNjFmMWQxMC5tcDQ_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwOTE0JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDkxNFQyMzIxNTBaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT0yMDY5Zjc0MDQ4Zjc0NjNmMmJmYTY3NWJjYWIxM2ZmNDliZjkzODJhZjlkZWYyYTQxM2QzNTgxNGIzYWM1OGI0JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZyZXNwb25zZS1jb250ZW50LXR5cGU9dmlkZW8lMkZtcDQifQ.UHchBXkRdPt5nYXJQ6bVzjfX69AegC2ck4uiydzKlps)
Not a reader? [**The whole thing in twenty slides**](https://vstorm-co.github.io/agenticos/presentation/) — what the problem is, what a spec holds, where it answers, and what it refuses.
## ⚡ Quick start
One command, and Docker is all it needs. It downloads one compose file, pulls the
published images, asks four questions, and hands back a console with a working
agent in it. Nothing leaves your machine.
```
curl -fsSL https://raw.githubusercontent.com/vstorm-co/agenticos/main/scripts/quickstart.sh | bash
```
**macOS**
Docker Desktop or [OrbStack](https://orbstack.dev). Nothing else.
**Linux**
```
curl -fsSL https://get.docker.com | sh
sudo apt install docker-compose-plugin
```
**Windows**
Through WSL2. In an administrator PowerShell:
```
wsl --install
```
Then Docker Desktop with WSL2 integration on, and run the installer inside the
Ubuntu shell it gives you.
### What it asks
| | |
| --- | --- |
| **Which model** | OpenAI, Anthropic, Google, OpenRouter — or *decide later*, which creates everything and lets you paste a key in the console |
| **Your key** | Typed hidden, stored encrypted in your own database, never printed back |
| **Your login and organization name** | Defaults are fine for a look around |
| **One switch** | Mirror the public MCP registry so all 5,802 tool servers are searchable by name |
Add `--check` to only find out what is missing, `--dry-run` to see every command
it would run without running one, or drive it unattended:
```
curl -fsSL https://raw.githubusercontent.com/vstorm-co/agenticos/main/scripts/quickstart.sh | bash -s -- \
--yes --provider anthropic --api-key sk-ant-... --org "Acme"
```
### Or type the three commands yourself
The installer is a wrapper around these, and there is no step it takes that you
cannot take by hand:
```
mkdir agenticos && cd agenticos
curl -fsSLO https://raw.githubusercontent.com/vstorm-co/agenticos/main/docker-compose.yml
docker compose up -d # postgres (pgvector), redis, api, prefect, console
docker compose exec -T -e BOOTSTRAP_API_KEY=sk-... app \
agenticos cmd bootstrap # an org, an owner, a key, a model, a published agent
open http://localhost:3000 # sign in as [email protected] / admin123
```
The images are `ghcr.io/vstorm-co/agenticos-backend` and `agenticos-frontend`,
published for amd64 and arm64 by every release; `AGENTICOS_VERSION=x.y.z` in a
`.env` beside the file pins one. There is no `.env` to write first: every
compose variable has a default. To change the code, `git clone` and `make dev`
instead - a clone builds the same images from the tree.
If something does not come up, `docker compose exec app agenticos cmd doctor`
answers the only question that matters — can this deployment actually run an
agent — and [docs/install.md](https://github.com/vstorm-co/agenticos/blob/main/docs/install.md) has the rest.
## What you get
- 🧰 **The harness, as configuration.** Retrieval over your documents, a real browser,
Python in a sandbox with files and a shell, charts, images, delegation —
switched on per agent, not wired into code.
- 📄 **Context files.** `AGENTS.md` and `CLAUDE.md` as a page: standing
instructions written once, attached to every agent that needs them.
- 🎓 **Skills.** A procedure written once in plain language, loaded when the
agent decides it is relevant. Edit it; live on the next answer, no release.
- 🔌 **MCP, at registry scale.** **5,802 servers** in the catalogue, searchable
by name — 99 of them checked by hand with their OAuth wired. Or any URL.
- 📚 **Documents read properly.** Pick the PDF reader per collection, or for one
file: PyMuPDF built in, LlamaParse where the tables carry the meaning,
self-hosted LiteParse OCR for scans. Plus how it is split, and OCR language.
- ⏰ **Automations.** Schedules and event triggers — the 07:00 triage, the Monday
summary. Same limits and same record as anything a person asked for.
- 📡 **One runner, eight surfaces.** Web chat, a hosted page, a widget, the HTTP
API, a raw WebSocket, Slack, Telegram, Mattermost. Published once.
- 🖥️ **A browser is all it needs; a desktop app if you want one.** The console is
a web app. The [desktop app](https://github.com/vstorm-co/agenticos/blob/main/docs/desktop.md) is the same console in a window of
its own - plus a pet on the desktop and a shortcut that screenshots straight into
a new chat. An add-on, never a requirement.
- 🛡️ **Governed.** Budgets that stop a run before the model request, approval on
anything side-effecting, an audit trail, tenant isolation in the schema.
- 📊 **A dashboard each person arranges.** 35 cards — runs, spend, service
health, answer quality, sandbox capacity — each gated on what that reader may
see. A finance lead and an engineer keep different ones on one deployment.
**Code defines, configuration composes.** A business team assembles agents in a
browser and never opens Python; engineers extend what there is to assemble, and
configuration can only ever reach what code registered. The ceiling is the
registry, not a config file — and it is Apache-2.0, on your hardware.
## What it looks like
### Inside one agent
An agent is a **spec**: instructions, a model, the capabilities it may reach,
the knowledge bound to it, a budget, and where it answers. Nothing ships until
**Publish**, and every publish is a version.
[Defining an agent: instructions, model, and the version that is live](https://github.com/vstorm-co/agenticos/blob/main/docs/assets/screens/dark/builder-build.webp)
| | |
| --- | --- |
| **Toolbox** — What the agent may do, as switches — your documents, a browser, Python, charts, delegation. Each one can require a person's approval first. This is the **AI harness**, assembled in a form. [Toolbox](https://github.com/vstorm-co/agenticos/blob/main/docs/assets/screens/dark/builder-toolbox.webp) | **Visual map** — The agent as a graph: what reaches it, what it reaches for. A dashed box is something nobody attached. [Visual map](https://github.com/vstorm-co/agenticos/blob/main/docs/assets/screens/dark/builder-visual-map.webp) |
| **Limits** — A monthly cap per agent, checked *before* each model call rather than added up after — plus a step limit, for the loop that is cheap and never stops. [Limits](https://github.com/vstorm-co/agenticos/blob/main/docs/assets/screens/dark/builder-limits.webp) | **History** — Every version it has had, still readable. Rolling back is a click. [History](https://github.com/vstorm-co/agenticos/blob/main/docs/assets/screens/dark/builder-history.webp) |
These four are dark only — the light half has not been captured.
### The first screen
**Dashboard** — 35 cards, laid out by whoever is reading: runs, spend, service
health, answer quality, sync freshness, sandbox capacity. Each one gated on what
that person is allowed to see, so a finance lead and an engineer keep different
dashboards on the same deployment.
The dashboard: 35 arrangeable cards
### Running forty of them
| | |
| --- | --- |
| **Agents** — Every agent you run, with the version that is live and who may use it. Agents | **Templates** — Start from one built for your industry; you get a draft to adjust and publish. Templates |
| **One answer, opened up** — Every answer recorded: the question, what it looked at, every tool call, the duration, the cost to a fraction of a cent. One answer, opened up | **How your documents are read** — Three PDF readers — PyMuPDF, LiteParse, LlamaParse — plus chunking and OCR. Per collection, overridable on the next file. A scanned price list and a contract do not want the same one. How your documents are read |
| **Context** — Standing facts — product names, policy, house tone — in one place instead of forty prompts. Context | **It asks before it acts** — Anything that sends, files or refunds waits for a person, with the intended action written out. Decided exactly once.