Houston · Cloud Design Guide

# How Houston runs in the cloud.

The Houston desktop app puts one agent on your machine. Houston Cloud puts ten thousand agents on a cluster, each one in its own sealed box, woken on demand, billed only when it works. This is how every piece of that stack fits together, written so a non engineer can follow it.

Start reading Jump to roadmap

## Reading legend

Each chapter has a status pill. Four states.

- Shipped already in the codebase today.
- Partial some of it works, the rest is on the plan.
- Planned proposed design, not built yet.
- Gate plan sequencing, decisions, and what triggers the build.

## The big idea, in one paragraph

Houston Cloud is the same `houston-engine` from the desktop, packaged in a tiny Linux box, and run one box per agent on Kubernetes. Each box is sealed off from the others using Firecracker microVMs. When nobody is talking to an agent, the box sleeps and costs nothing. When a message arrives, the box wakes up in under a second, does the work, and goes back to sleep. A small control plane in front of it all handles login, permissions, and routing messages to the right box. That's it. The whole guide is just zooming into each of those words.

## The chapters

01 Plan
The plan
The whole thing on one page. The summary of every chapter that comes after.
02 Planned
Kubernetes
The thing that runs all the boxes. Explained without the buzzwords.
03 Planned
Kata + Firecracker
How we make each agent's box bulletproof. Tiny VMs, big walls.
04 Planned
Knative
The reason sleeping agents cost zero. Wake on demand, fall asleep on idle.
05 Planned
The control plane
The doorman. Routes messages, checks permissions, wakes the right box.
06 Planned
Postgres + Redis
Where the long term memory lives and where the short term memory lives.
07 Planned
Storage
Where each agent's files survive when its box is sleeping.
08 Planned
Networking
Walls between teams. The HR agent and the Sales agent can't see each other.
09 Partial
Auth
Login, sessions, who-can-talk-to-which-agent. Supabase doing the heavy lifting.
10 Planned
End-to-end flow
User clicks Send. What happens, in order, all the way to the agent's reply.
11 Gate plan
The roadmap
What gets built first, what waits, what the gates are.