How to Start Building an AIOS

Everyone is building agents. Almost nobody is building the thing agents are supposed to work inside.

That's the gap, and it's why so many impressive agent setups never turn into anything. You wire up a crew, you give them tools, and six weeks later you have a beautifully organized machine that has never once talked to a customer. The agents work on the agents.

An AIOS is the other thing. An AI operating system is the software layer that does your business's recurring work — publishes the content, sends the outreach, watches the ad spend, answers the phone — and keeps doing it whether or not you're awake. Agents are the workers. The AIOS is the company they work for.

I run mine on one box I own, for a fixed monthly ceiling I set myself. This is how I'd start it again from nothing.

The full build, in order

This page is the architecture. Each part below has its own guide, and they are meant to be built in this order.

The org chart. Who does what, and the one rule that lets you leave — deploy rights exist only where you own the hardware. Draw the chart first.

The division wall. One shared file every agent reads before it starts and writes to when work ships. How twenty agents stay out of each other's way.

The shared brain. Stop paying your AI to re-read everything and forget it by morning. Give it a memory instead.

The first real job. An AIOS with no job is a hobby. Mine publishes. Here is that build, with the prompts.

The one thing only you can do. Ninety seconds of voice memo goes in. Everything after it runs without me. How that works.

Two more are coming: the watcher that wakes you the moment a crew reports, and the lifeline that lets you reach and steer any agent from your phone.

The test that separates an AIOS from a toy

Before you write a line: name the job.

Not a capability. A job — something you do by hand, on a schedule, that makes or saves money. Publishing this week's content. Sending the day's outreach. Following up with every lead who didn't answer. Checking what the ads did yesterday.

If you can't name it in one sentence with a dollar attached, you're not building an operating system. You're building a demo.

Name what finished looks like in the same breath, and write both down. Published means indexed, not drafted. Sent means delivered, not queued. Those definitions become the first two lines of the file the whole system reads, and you'll be glad you wrote them while you were calm rather than at nine on a Monday.

My first one was content. I was recording ideas into my phone and then losing two hours a day turning them into something publishable, which meant on busy weeks I published nothing. So that became job one: a ninety-second voice memo goes in, a finished article comes out on ground I own, and it gets cut down and posted to every channel. My hands touch the memo. Nothing else.

One job. End to end. Finishing without me is the whole requirement — a system that gets it 80% there and hands you the rest isn't an operating system, it's a to-do list that writes itself.

Build one loop, not a platform

The instinct is to design the whole thing. Resist it, because you'll spend three weeks on plumbing and never ship the part that pays.

Take your one job and follow it all the way from trigger to receipt. What starts it? What does it need to know? What does it produce? Where does the finished thing go, and how do you find out it happened?

Then build exactly that path and nothing else.

The second job costs you a fraction of the first, because everything under it — the door, the brain, the ledger, the memory, the rulebook — is already there. That's what the next section is about. Build them once, in service of one real job, and the rest of the company snaps on top.

The five parts every AIOS needs

These five are the whole architecture. Everything else is detail.

One door in. Every request enters through a single endpoint. Not a webhook here and a form there and a cron job somewhere else — one door, authenticated, that logs everything that passes through it. It sounds like a constraint and it's a gift: when something misfires at 3am you have one place to look. Mine is a single endpoint called /dispatch. Anything that wants the system to do something knocks there.

One brain. Every call to a model goes through one function. Not "mostly." Every one. That single choke point is where you set which model does what, where you cache prompts, and where you count what you spent. The moment one module imports the SDK directly and calls out on its own, your cost numbers are fiction and you won't find out until the bill arrives.

One ledger. Money is metered before the call and recorded after it, with a key that makes the record impossible to write twice. This matters more than it sounds. A timeout does not mean nothing happened — it means you don't know. If a retry can charge you twice, you'll eventually retry a hundred things at once and find out the expensive way.

One memory. Its own database, on its own box, holding its own state. No shared account, no borrowed identity, nothing that breaks when a system you don't control changes. If you can't rebuild the whole thing from a git clone, an env file and one command, you don't own it — you're renting it from your own past self.

One rulebook. Every number the system judges your work against, in one plain file you can edit — not buried in code. What counts as too long. What counts as too expensive. When a thing is finished, and when it has failed.

This is the part I got wrong for months, and it's easy to get wrong because it doesn't look like a mistake while you're making it. You write a check into the code as you build, the number seems obvious at the time, and six weeks later it's blocking work at nine in the morning and you cannot remember agreeing to it. Mine trimmed a piece to fit a word limit I had never set. Changing that number took a code change, a review and a deploy — for a figure I invented on a Tuesday and never decided.

So put every one of them in a file. Then the rule that makes the file worth having:

When you disagree with the machine, you edit the file. You don't argue with the machine.

That one habit turns the file into the place your judgement accumulates. Every time a gate stops you and you decide it was wrong, the correction lands somewhere permanent instead of somewhere you re-litigate next month.

Two conditions make it hold. A missing file falls back to sane defaults, so a fresh copy of the system still runs. And a missing number is never guessed — the system says that rule has no threshold and skips the check rather than inventing one, because a made-up limit is worse than no limit.

One more detail that decides whether anyone uses it: when a check refuses something, the message names the rule and the file it came from. "Body is 2,218 words" starts an argument. "body_max_words is 2000, in your rulebook" ends one, because you already know where to go.

graph TD
  D[One door in: every request, authenticated and logged] --> BR[One brain: every model call through one function]
  BR --> LG[One ledger: metered before, recorded after, keyed so it cannot double]
  LG --> ME[One memory: its own database, on its own box]
  ME --> RB[One rulebook: the numbers you judge the work by, in a file you edit]
  RB --> J[Your one job, running end to end]
  J --> J2[The second job costs a fraction of the first]

Two rules that keep the bill sane

The thing everyone gets scared about is cost, and it's a solved problem if you're deliberate on day one.

Deterministic work never touches a model. Uploading a file, writing a row, posting to a channel, calling an API that returns exactly what you asked for — none of that needs intelligence, and routing it through a model is how people end up with a hundred-dollar day doing work a script does for nothing. Reserve the model for judgment. Use plain code for everything else.

Cheap by default, expensive on purpose. Set the small fast model as the default for every task, then promote the specific jobs that visibly need more. Most of what an operating system does all day is classification, extraction and formatting — work the cheap model does perfectly well. My whole system runs under a hard ceiling I set in the console, with a second softer ceiling the system reads out of the rulebook and refuses the call before it's made rather than after. That second number belongs in the file, not the code — it's the one you'll want to move the first month you get busy.

Two ceilings, one default. That's the entire cost strategy, and it's why I sleep fine with twenty agents running.

Where people go wrong

Four failure modes, all of which I've either hit or watched somebody hit.

Agents that work on agents. The most common one by far. If your system's output is a better version of your system, you've built a hobby with a build pipeline. Point it at revenue or turn it off.

Every module calling the model directly. It feels harmless the first time. Then you have eleven call sites, no idea what any of them costs, and no way to change models without touching all of them.

No idempotency. Retries are unavoidable. Double charges are optional. Give every paid action a key and write the record as insert-or-ignore.

Editing the server directly. You'll fix one thing on the live box at midnight, forget, and lose it in the next deploy — or worse, lose the only copy that ever existed. Git is the truth. The box is a place the truth gets copied to.

Judgement written into code. The quiet one. Every limit you hard-code is a decision your future self has to re-open a pull request to change, and by then nobody remembers making it. If a number is a matter of taste, it goes in the rulebook. If it's a matter of contract, it goes in the code. Getting that line wrong is why people end up fighting their own system.

Your first week

If I were starting Monday with nothing:

Day one. Write down the one job. One sentence, with the dollar figure it costs you today in time or missed work.

Day two. Build the door and the brain. An endpoint that authenticates and logs, and a single function every model call goes through. Nothing clever. A hundred lines.

Day three. Add the ledger and the ceiling. Check before you spend, record after, refuse when the month's number is hit — and put that ceiling in the rulebook file rather than in the code, because it is the first number you will want to change.

Day four and five. Build the one job end to end, using only those pieces. Make it finish and tell you it finished.

Day six. Run it on real work. Not test data — the actual thing, the actual channel, your actual name on it.

Day seven. Write down what broke. That list is your second week.

You'll have something running in a week that does one real job every day forever. That's worth more than a six-month architecture you never turn on.

What it buys you

The obvious answer is time, and that's the small one.

The real one is that the work stops depending on you being available. Not on you being fast — I was always fast. On you being present. Every business I built before this needed me physically there for the last inch of everything, which meant a sick day cost the company a day and a vacation cost it a week.

An AIOS removes that inch. The job runs, finishes and reports, and the only thing that reaches you is the decision that genuinely needed a person — the rest were settled in the rulebook weeks ago, by you, in a calmer mood. When that's true for one job, it's a relief. When it's true for the four or five jobs that run your business, the desk stops being the place where work happens, and you can go do the thing you started a company to be able to do.

That's the whole point of it. Not agents. Not automation for its own sake. A business that keeps working while you're in the water.

Start with one job. Build the door, the brain, the ledger, the memory and the rulebook once. Then add the second job, and watch how much less it costs than the first — and when more than one agent is working inside it, give them a shared channel before they start overwriting each other.

If you want help deciding which job to start with, book a working session and we'll pick it together.