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.}

Quick start · Screens · Presentation · Docs · Why an OS · Comparison

English · Polski · Deutsch · Español

---

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

And the same console on the desktop, with company: the optional desktop app, its pet, and a shortcut that screenshots straight into a new chat.

pet.mp4

_{Not a reader? The whole thing in twenty slides — 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. 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 admin@example.com / 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 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 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.

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.	Visual map — The agent as a graph: what reaches it, what it reaches for. A dashed box is something nobody attached.
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.	History — Every version it has had, still readable. Rolling back is a click.

_{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.

Running forty of them

Agents — Every agent you run, with the version that is live and who may use it.	Templates — Start from one built for your industry; you get a draft to adjust and publish.
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.	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.
Context — Standing facts — product names, policy, house tone — in one place instead of forty prompts.	It asks before it acts — Anything that sends, files or refunds waits for a person, with the intended action written out. Decided exactly once.
What it costs — Spend by period and by agent. The cap is checked before the model is asked, so a runaway stops mid-sentence instead of arriving as an invoice.	Keys and credentials — Every key, encrypted and separated per team. Replaceable, never readable again — including by whoever runs the server.
The tools you already pay for — 5,802 MCP servers in the catalogue, searchable by name, 99 of them checked by hand with their OAuth wired. Or any server by URL. No connector to write.	Where people meet it — Slack, Telegram, Mattermost, a website widget, your own software over the API. Published once; same limits everywhere.

_{Screenshots follow your GitHub theme. All 35 screens.}

The best agentic OS you can run yourself

That is a claim, and the only honest way to make one is to hand over the criteria and let you count. An operating system does seven things. Each row below is a mechanism you can read in the source, not a promise.

What an operating system does	What AgenticOS does
Runs and isolates processes	Runs agents, stops one at its budget, isolates tenants in the schema rather than in service code, and keeps every run with what it cost
Enforces resource limits - quota, cgroups	Monthly budgets per agent, checked before each model request rather than tallied afterwards. A run that fails still records what it spent
Controls access - users, permissions, sudo	A permission catalog in code, roles composed from it, per-resource grants that widen and never narrow. approval: required is the sudo: a tool that acts on the outside world waits for a person
Reaches hardware through drivers	One interface to 27 model providers and to any MCP server by URL. Change a model profile and every agent using it moves, without one of them being republished
Keeps a filesystem	Collections, skills and attached context in your own Postgres, with embeddings keyed per organization
Gives many interfaces one shell	One runner behind web chat, the HTTP API, Slack, Telegram, a widget, a hosted page and a schedule. Same budget, same approval gate, same audit trail
Writes an audit log - syslog, auditd	Who ran what, when, what it cost and who approved it. Written even when the run failed

Apply the same seven to anything else in the category. That is the test we would like to be judged on, and When to use something else is where we run it against the alternatives - including the rows where the honest answer here is "not yet".

Now apply the same seven to anything else in the category — including the ones with a thousand times our stars. None of them explains why it is an operating system, because most of them are a workspace with the letters on the box. That is the whole claim: not that we have the most users, but that we are the only one that states the criteria and then meets them in code you can read.

Where the honest answer here is still "not yet", it is a row in the comparison below and a line on the roadmap. When to use something else is the long version, including where this one loses, and what makes something an operating system for agents is the criteria on their own — take them and score anybody, us included.

What an agent can do

Switched on per agent, in the Builder. Each carries its own settings, its own permission scope and — where it acts on the outside world — its own approval gate.

Answer from your documents	Retrieval over collections in your own Postgres, plus skills it loads on demand and context files bound across agents
Go and find out	Web search, fetch one page properly, or drive a real browser through a site that needs clicking
Do the work	Run Python, keep a sandbox with files and a shell, draw charts, generate images
Handle what is too big for one answer	Delegate to subagents, keep a task list, think longer, compact a long conversation
Stay inside the lines	Guardrails that redact or block, per-tool output caps, and the clock
Anything else	Any MCP server by URL - 5,802 in the catalogue, 99 of them checked with their OAuth flows wired, and no connector to write

Where it answers

Publish once. The same runner serves all of these, so an answer does not depend on where the question came from.

Web chat	In the console, with attachments and slash commands
The desktop app	The same console in a window of its own, with a pet and a screenshot shortcut - an optional shell, not a second product
A hosted page	/e/{key} - send somebody a link, no account needed
An embeddable widget	On your own site, with variables from the address bar
The HTTP API	One POST and you have an answer
A raw WebSocket	Stream tokens into a frontend you built yourself
Slack, Telegram, Mattermost	Where an @mention runs as the person who sent it, not as the bot
Schedules and triggers	A clock, a webhook, or a mailbox we poll - routines

On the desktop, if you like

Everything above runs in a browser, and that is how most people use it. For those who want it on the dock there is a desktop app: a thin shell around the same console - same sign-in, same permissions, nothing bundled - with two things a browser tab cannot do. A pet that lives on the desktop while you work, and a global shortcut (⌘⇧A) that takes a screenshot of any region and opens a new chat with it attached.

_{Amigo, one of five pets. Drag it, click it, stroke it; right-click for its menu. No more caramba in your AI.}

Compared with the alternatives

The only one of these you can run to completion on infrastructure you already own, with agents a non-engineer edits and an accountant can audit.

	AgenticOS	Cloudflare OS	Glean	A library
Open source	✅ Apache-2.0	✅ Apache-2.0	—	✅
Runs on ordinary infrastructure (Postgres, Redis, Docker)	✅	—	—	✅
Runs air-gapped, no vendor account	✅	—	—	✅
Local models (Ollama, LiteLLM)	✅	✅	—	✅
Agent built and edited by a non-engineer	✅	~	✅	—
Versioned on publish, exportable into your git	✅	~	—	—
Budget that stops a run before the model call	✅	~	~	DIY
Human approval on side-effecting tools	✅	✅	~	DIY
Multi-tenant isolation in the schema	✅	~	✅	DIY
Per-organization secret vault	✅	✅	✅	DIY
Any MCP server by URL, 5,802 in the catalogue	✅	✅	~	~
Slack, Telegram, widget, hosted page and API from one runner	✅	—	~	DIY
ACL-aware connectors to 275+ SaaS systems	—	~	✅	—
Evaluation harness	—	—	✅	~
SAML / SCIM	—	✅	✅	—

_{✅ first-class · ~ partial or via configuration · — not available · DIY you wire it yourself. "A library" means LangGraph, Pydantic AI or similar. Reflects each project as of 2026-08; corrections welcome via PR. The last three rows are ours to fix and are on the roadmap.}

Why it exists

Most agent frameworks give you a library. You write Python, you deploy it, and every change to an agent's behaviour is a pull request, a review and a release. That is the right shape for a product feature and the wrong shape for the forty small agents a company actually wants — because the person who knows what the agent should say is not the person with commit access.

AgenticOS moves the agent out of the code and puts governance around it instead. Secrets are sealed per organization: a key copied from one tenant's database row cannot be decrypted for another, and no API response ever returns one.

Docs

Install · Your first agent	From nothing to an agent that answers
Concepts	Spec, version, exposure, trigger, run — the five nouns
Permissions · Governance	Who may do what; budgets, approvals, audit
Capabilities · MCP	What an agent can do, and how to add a tool
Models · Secrets	Providers, profiles, cost; the vault
Knowledge · Skills	Parsers, chunking, OCR; written know-how
Channels · API	Slack, Telegram, widget, WebSocket, HTTP
Desktop app	The optional shell: the console in a window, the pet, the screenshot shortcut
Architecture · Testing	How it is built, and how it is verified

Built with MkDocs: make docs serves them on :8001. Stack, in one line: FastAPI

• Pydantic v2, PostgreSQL with pgvector, Redis, Prefect, Pydantic AI, Next.js 15. Nothing phones home — the only outbound calls are the ones your agents make.

Contributing

make check before a pull request: every CI job except e2e, about five minutes. New behaviour ships with a test; a bug ships with a regression test. The platform layer is held at 100% coverage and CI fails below it.

Three things that trip up a first change: a tool is code and an agent is not (there is no @agent.tool — a capability registers, and then it is a switch in everybody's Builder); require(...) gates go on collection routes only; and if the tool already exists as an MCP server, write none. CONTRIBUTING.md has the rest, .claude/ has the same conventions written for a machine, and good first issues are labelled here.

The rest of the Vstorm OSS ecosystem

Everything below runs on Pydantic AI.

Project	What it is
full-stack-ai-agent-template	The generator AgenticOS was built from — FastAPI + Next.js 15, RAG, streaming, auth, 20+ integrations
pydantic-deepagents	Open-source, self-hosted Claude Code — a terminal assistant and the framework behind it
pydantic-ai-shields	Guardrails — cost tracking, prompt-injection detection, PII filtering, secret redaction
subagents-pydantic-ai	Nested subagent delegation, parallel execution, task cancellation
pydantic-ai-backend	File storage and Docker-isolated sandboxes, with a permission system
pydantic-ai-todo	Hierarchical task planning with PostgreSQL storage and an event system
production-stack-skills	Skill pack that turns a coding agent into a senior production engineer
content-skills	Content studio skill pack for coding agents — brand-aware, with built-in anti-slop

Browse them all at oss.vstorm.co.

Browse them all at oss.vstorm.co.

Licence

Apache License 2.0 - see LICENSE and NOTICE. THIRD_PARTY_NOTICES.md lists every component the images ship and its licence; the review of what those licences oblige, and the findings still open, is in the documentation.

Apache-2.0 rather than MIT because AgenticOS is meant to be deployed inside other companies: the explicit patent grant is the part their legal review asks about, and MIT is silent on it.

---

Need help putting agents into production?

We are Vstorm — an applied agentic AI engineering consultancy with 30+ production agent implementations.
AgenticOS is what we build them on, and we deploy it inside client infrastructure: your cloud, your data centre, or air-gapped.

Built with care by Vstorm · oss.vstorm.co