How Shadow-OS works, in full

One account, two very different jobs

Shadow-OS is a personal AI agent, and it is also the place you create agents that serve other people. Those are not two products that share a login. They are the same kernel, the same memory system and the same tool layer, running under different scopes.

Your personal agent works for you: it remembers what you tell it, runs work on a schedule, reads and writes files, searches the web, and reaches you on the web app or on WhatsApp. A business agent works for your customers: it answers from knowledge you give it, books appointments, escalates what it cannot answer, and keeps a profile of every person it has spoken to.

You talk to a business agent in two capacities, and it knows the difference. Through its public link you are a customer and see exactly what a customer sees. From the console you are its manager, and it sees your customer roster and acts with your authority.

Where it runs, and why that matters

The same agent is reachable from the web app, from WhatsApp, and from a developer API. This is not three integrations of a chatbot — it is one agent with one memory, so something you told it on WhatsApp is known in the web app, and a file it produced for you on the web can be sent to your phone.

On WhatsApp it handles voice both ways: a voice note you send is transcribed and understood, and it can reply with a spoken message rather than text. Real-time phone-style calls are not supported today.

Memory: what is remembered, and what is deliberately not

There are two layers, and the distinction is the whole design.

Durable facts follow you everywhere. When you tell it something lasting about yourself — your language, your work, a preference — that is stored once and surfaces in every later conversation, on any channel. You never have to reintroduce yourself.

Conversation content does not leak between conversations. Each session is a separate scope: the files, documents and search index of one conversation are not visible from another. That is why a developer can run many isolated sessions through one API key without their data mixing, and why a support conversation with one customer never surfaces in another's.

• Durable, cross-conversation: facts about you, and what a business agent has learned about its business.
• Session-scoped: uploaded files, indexed documents, the working directory, and the search index over them.
• Per-customer: each customer of a business agent has their own conversation and their own living profile, visible to the owner and to no other customer.

What a business agent actually knows

Its knowledge comes from documents you give it. They are indexed and retrieved by meaning rather than keyword, so a customer asking "do you do gluten free" finds the line in your menu that says "celiac-friendly options available," which a keyword search would miss.

It also knows its people. Every customer who arrives through the link or WhatsApp gets a member record, a display name once it learns one, and a short profile the agent maintains itself: who they are, what they want, what was agreed. That profile is why the second conversation does not start from zero.

And it knows what it does not know. When a customer asks something its knowledge cannot answer, it records that as a gap rather than improvising, and the gap is waiting for you in the console.

The part that compounds: it learns from your answers

When the agent cannot answer, it escalates: the customer is told a human will confirm, and you get a notification. You answer once. Two things then happen.

The customer receives your answer in the agent's own voice, as confirmed information from the business — not a robotic forward. And, when your reply establishes something lasting, it is distilled into a fact and saved to the agent's permanent knowledge, so the next person who asks never waits at all.

The judgement there is deliberate, and it is the reason this is useful rather than dangerous. Most replies to a customer are not business facts. "Sure, I'll put one aside for you" is a promise to one person. "I'll call you in ten minutes" is already stale. "Yes, we deliver to Florentin until 20:00" is a policy everyone needs. Only the third is learned. Replies about one named person, arrangements true only today, and anything that reads as an exception rather than a rule are not saved, because the knowledge base is served to every customer and a wrong fact there misinforms all of them.

You see what was learned, so you can correct it. Nothing is absorbed silently.

Teaching it to use your own systems, in chat

This is the line between an agent that answers and an agent that operates. If your business runs on something with an API — a CRM, a booking system, stock, shipment tracking — you can teach your agent to call it by describing it in conversation. No developer, no webhook, no integration to configure.

You tell it the endpoint, the method, what the call is for and when it should be used, and any credential it needs. It saves that as a reusable tool, and from then on it can use it for every customer of that business.

Once saved, a customer asking "where is my order?" gets a real answer from your real system, in the middle of a normal conversation.

• Only the owner can teach, change or remove an API. Customers cannot, and never see that these tools exist.
• The credential is stored server-side and is never shown again, never sent to the model, and never revealed to a customer — you re-enter it if you want to change it.
• Placeholders in the URL, query or body are filled by the agent at call time from what the conversation actually provides.
• You can list what it has been taught and remove any of them at any time.

You:   I want you to be able to check order status.
       It's GET https://api.myshop.com/orders/{{order_id}},
       with header Authorization: Bearer sk-live-…

Agent: Saved as track_order. I'll use it when a customer
       asks about an order and gives me an order number.

Customer: where is order 48213?
Agent:    It shipped yesterday and is out for delivery today.

Automation: you ask for it, you do not build it

There is no workflow builder, and that is a design decision rather than a missing feature. You describe the outcome in a sentence — "every weekday at 08:00, email me a summary of my unread mail," or "tell me if the price on this page drops below 8000" — and the agent creates the recurring work itself.

Three kinds exist. Scheduled tasks run at a time, once or repeatedly. Watches check something on an interval and alert when a condition fires. Recipes are multi-step workflows the agent saves so it can repeat them reliably, with a run history.

A scheduled run is not a replay. Each run starts a fresh conversation and does the work again from scratch, because a task that re-sends last week's file while claiming it is new is worse than one that fails loudly. The previous run's result is given to it as context so it can tell you what changed — never as evidence that the work is already done.

Files, and the two ways to give it one

The distinction matters more than it looks. Indexing a document extracts its text and embeds it so the agent can FIND things in it — right for a contract, a manual, a price list. Adding a file to the workspace keeps the real bytes so the agent can READ, EDIT and RUN it — right for a spreadsheet, a script, anything it has to work on rather than quote from.

It writes real files too: documents, spreadsheets, images, charts, PDFs, audio. A file it creates is checked before it is handed over — code it writes is parsed, and it is told to fix an error before delivering rather than after you find it.

The developer API

Everything the product does is reachable programmatically: conversations, memory, documents and semantic search, the workspace, automation, notifications, and the whole business-agent surface — creating agents, their knowledge, customers, appointments and analytics.

The official Python SDK is on PyPI. Sessions are isolated from each other, so one key can serve many end users without their data mixing.

pip install shadow-os

from shadow_os import ShadowOS
client = ShadowOS("sk-shadow-…")

client.chat("Summarise my unread mail", session_id="user-42")

Bring your own model

You can run the whole platform on your own provider and your own key — OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint — and set how hard it should think per call. The key travels with the request, is used for that turn, and is discarded. It is never stored, which is exactly why it is passed per call rather than saved in a settings page.

The platform's own model stays available and is the default. Bringing your own is a choice, not a migration.

How the work is checked

An agent that confidently reports work it never did is worse than one that fails. Several checks run on every turn and none of them ask the model to grade itself.

If the answer claims a file was produced, the platform verifies a file-producing tool actually ran this turn and that the file exists — a claimed delivery with nothing behind it is rejected and the work is redone. Code written into a file is parsed before delivery. Deliverables are scanned for the two ways models pad work: leftover placeholders, and filler repeated to reach a requested length. Search results carry their real publication date and age, so an answer about the present cannot quietly rest on an article from eleven years ago.

These are mechanical checks, deliberately, because a model asked whether its own work is good will usually say yes.

Isolation and what the owner controls

Every business agent is sealed from every other. A credential grants access to one agent and nothing else, and access to an agent is not access to act as a particular person — a public link cannot be used to read another customer's conversation.

Customers can disconnect. Once someone opts out the business cannot message them again, on any channel, including by answering an older question. Outbound messages to customers are rate-limited per person, so the tooling cannot be turned into a broadcast machine by accident.

The owner can see everything their agents did, remove knowledge, revoke a link or a key, and delete an agent entirely.

The honest limits

Real-time voice calls are not supported; WhatsApp voice works as voice notes in both directions. The free tier has a monthly usage quota, and the hosting the free plan runs on sleeps when idle, so the first request after a quiet period can take a while to answer.

An agent is only as good as the knowledge you give it. The learning loop shortens that work considerably, but the first week still involves answering questions it has never seen.

Key takeaways

• One kernel and one memory serve both your personal agent and the agents you build for customers.
• Durable facts about you follow you everywhere; conversation content stays inside its own session by design.
• Answering an escalation once can become permanent knowledge — but only when it is a lasting fact, never a one-off promise or anything naming a customer.
• You can teach your agent to call your own API by describing it in chat; only the owner can, and the credential is never shown again.
• You do not build automation, you ask for it — and a scheduled run redoes the work rather than replaying the last result.
• Claimed deliverables are verified mechanically, because a model grading its own work will usually pass it.

Keep reading