Houston · Engine Design Guide

# How the engine actually works.

A walkthrough of every piece of Houston, what it does today, what it should do next, and the reason for every decision in between. If you are a new hire, you should be able to read this top to bottom and start building. If you need more, the code is linked at the bottom of each chapter.

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, code not written yet. Some planned work is gated.
- Gate plan sequencing, decisions, and acceptance gates.

Each planned chapter also lists which milestone it belongs to (M1a, M1b, M2, M3, M4, M5) and a rough size in weeks or months. Sizes are honest estimates, not commitments. Where the work depends on something else landing first, the chapter says so.

## The big idea, in one paragraph

Houston is a desktop app, an engine, and folders on disk. The desktop app is what users click. The engine is a Rust binary that does the work. The folders are where agents and their data live. The desktop talks to the engine over HTTP. The engine spawns provider CLIs (Claude Code, Codex, Gemini) and watches files. This guide separates shipped truth from proposed work: reliability and scoped auth can improve the native engine now; Linux runtime isolation is a later, spike-gated bet that only ships after cold start, migration, support, and entitlement risks are proven.

## The chapters

01 Shipped
The three layers
Desktop app, engine, agents. Three pieces, one architecture.
02 Shipped
An agent is a folder
No proprietary formats. Just files on disk today, with runtime relocation only if Chapter 3 ships.
03 Spike-gated · M3 candidate
Where the engine lives
Linux runtime is the isolation bet. Useful, expensive, and not committed until measurements pass.
04 Target · M1a
How a message flows through
The full chat-turn sequence. The most important diagram.
05 Diagnosis · feeds M1
Why conversations die today
Five failure modes. Same root cause: writes happen after work, not before.
06 M1a · 4-6 weeks
The reliability tables
The reliability floor: durable turns, replay, audits, and explicit retry semantics.
07 M2 guards · M3 kernel wall
Keeping agents apart
Three walls for three attack paths. Only kernel wall stops direct filesystem snooping.
08 M2 native homes · M3 runtime users
Logging in (still one click)
Per-agent OAuth without breaking the UX.
09 Triggers after M1a
External triggers
User chat and mobile ship. Cron ships in-app. Webhooks and Slack-style inbound channels need more work.
10 Candidate · M4+
Deployment: desktop, self-host, cloud
Always On exists. Cloud is a separate product with unresolved control-plane choices.
11 Gate plan
The roadmap
Milestones with gates, test contracts, and promises we are allowed to make.