The first architecture diagram showed the parts of TDK CLI. This one shows time: what happens, in order, after you type tdk up. Knowing the order tells you where a start can stop, and which message to read when it does.

The sequence below follows the repo's documented behaviour: the host check, the drift check before Tilt starts, the Starlark generation at Tilt load time, readiness, and the JSON result. Some steps are summarised, so check them against the code and the docs before you rely on one exact message.

The sequence 

sequenceDiagram autonumber actor Dev as Developer participant Agent as AI agent over MCP participant CLI as tdk CLI (TypeScript) participant Host as Host and container runtime participant Snap as Snapshots in .tdk-contract participant Tilt as Tilt participant Disc as Discovery (Starlark) participant Eng as Engine generators (Starlark) participant Dock as Docker participant Svc as Service containers Dev->>CLI: tdk up (or agent calls up) Agent->>CLI: up (MCP tool runs tdk up --json) CLI->>Host: check host type and container runtime alt canUp is false Host-->>CLI: no Docker, WebContainer, or Windows opt-in missing CLI-->>Dev: exit non-zero, tell the reason, do not spawn Tilt else canUp is true CLI->>Snap: compare generated files with saved snapshots alt a generated file was hand-edited Snap-->>CLI: drift found, name the file CLI-->>Dev: block the start, fix the source and retry else no drift CLI->>Tilt: spawn Tilt with the project Tiltfile Tilt->>Disc: load service.json files Disc-->>Tilt: resources, stacks, dependsOn Tilt->>Eng: generate per-service runtime files Eng-->>Tilt: write .autogenerated and service.yaml Tilt->>Dock: build images, start containers in order Dock->>Svc: start proxy, Postgres, services Svc-->>Tilt: health route answers Tilt-->>CLI: resources report ready or failed CLI-->>Agent: ok true, or ok false with errors CLI-->>Dev: TDK is up, with URLs and ports end end Note over Agent,CLI: The agent polls status until readiness.ready is true Agent->>CLI: status CLI-->>Agent: readiness ready, pending, or failures Dev->>CLI: tdk down CLI->>Tilt: stop resources Tilt->>Dock: stop and remove containers

The steps that can stop you

Four steps can stop a start, and each one tells you something different.

The host check. If canUp is false, the machine is the problem. No change to your project will help until the host has a working container runtime. The command exits without starting Tilt.

The drift check. A hand edit to a file under .autogenerated/ blocks the start and names the file. The fix is upstream: change service.json or the generator, then start again. This check runs before Tilt is spawned, so nothing has been built yet.

Readiness. up returns before the stack is ready, because a build can take longer than one command. The result tells you whether every resource is built, running, and healthy, or which one failed. tdk status --json answers the same question at any time.

The first failed resource. A failure in one service usually stops the ones that depend on it. Read the logs for the first failed resource, not the last. tdk logs --json --service <name> --tail 200 returns a bounded snapshot.

Where the agent fits

An agent does not replace this sequence. It calls the same commands through the MCP server. The useful part for the agent is the loop: call up, poll status until ready, read logs for any failure, then stop. The sequence above shows why the poll is needed. up returns before readiness.

Stopping cleanly

tdk down reverses the lifecycle: Tilt stops the resources, and Docker removes the containers. Run it when you finish. A stack left running keeps its ports, and the next up may refuse to start while an old Tilt still answers on its port.

Summary

One tdk up is a short chain of checks before any container starts: host, drift, then generation and readiness. Each check has its own message, and each message points at the fix. Read them in order, and most starts become a matter of reading the first line that failed.