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.
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
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.
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.
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.
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.