English | 简体中文 | 繁體中文 | 日本語 | 한국어
LLMs are brilliant at writing application logic, but notoriously terrible at maintaining local infrastructure. Every time your AI rewrites a Dockerfile, misconfigures a Tiltfile, or breaks an nginx.conf, it wastes your developer focus and burns thousands of unnecessary API tokens.
TDK CLI Core bridges the gap. You write the clean web application logic, and TDK instantly autodetects your stack to generate, link, and orchestrate the local environment for you.
No vendor lock-in. No tedious plumbing. Run a single command to natively orchestrate 72 different integration tiers including:
- Runtimes & Frameworks: Bun, Node, Python, Go, Rust, React, Vue, Svelte, Elysia, Fastify, NestJS
- Databases & Tooling: Prisma, Drizzle, Atlas, Dbmate
- Messaging & Gateway: NATS, Traefik
TDK is the local runtime for agent systems: the agent, its MCP tools, its database, its queue, behind one gateway, one command.
# Scaffold an agent, an MCP tools server, and a database in one stack
tdk resource bot --type agent --stack shop --yes
tdk resource tools-mcp --type mcp --stack shop --yes
tdk up shopAgents get durable checkpoint volumes that survive tdk down, sticky session routing via x-session-id, graceful SIGTERM drain during hot reloads, a Docker health check on /health, and application-level readiness checks on /ready. See the AI agents guide and honest comparison with agent frameworks.
TDK CLI — start services on your machine. It is not a deploy and not a Compose file: define each service in service.json, then run tdk up. No Kubernetes is needed on the machine.
Stability: 1.x local dev. Write service.json; TDK generates the local runtime files. See what TDK writes and how to check for drift. Core CLI is MIT and needs no key. Premium is optional.
Docker runs the containers. Tilt watches services and live-updates containers while you code. TDK CLI writes the configuration Tilt uses. Production deployment stays with Helm, Argo CD, or Kustomize.
Website · Quickstart · Examples · Awesome TDK · Demo · Report a bug
If TDK helps you run your local stack, a ⭐ on this repo helps other developers find it.
tdk ui opens an interactive terminal dashboard for inspecting running services. Move with ↑/↓ or j/k, search with /, and press 1–5 to jump between tabs. See docs/ui.md for every key binding.
- One
service.jsonper service. TDK generates the Dockerfile, Traefik routing, and Tiltfile from it. You do not hand-write adocker-compose.ymlornginx.conf. - Local stack without Kubernetes. Services run on Docker and Tilt on your machine. You do not need a local cluster such as kind or minikube.
- Hot reload while you code. Tilt live-updates the containers when files change.
- Generated files you can check.
tdkrecords the generated files and reports drift, so local config stays in sync. See generated files and drift checks.
Teams that run tdk up on their own code (listed with their consent in ADOPTERS.md):
- Lekast, TDK 1.3.178
- mfin.services, TDK 1.3.140
- MakeOffer, TDK 1.3.180
- Red Moon Digital, TDK 1.3.81
Using TDK too? Tell us or add a row to ADOPTERS.md.
If TDK saves you time, a ⭐ on this repo helps other developers find it.
mkdir shop && cd shop
tdk project --yes
tdk resource orders-api --type backend --stack shop --yes
tdk up shop
curl http://api.shop.localhost/api/orders/healthtdk up prints the host ports it chose. It uses port 80 when it is free, so URLs carry no port. Otherwise it picks one from 8080-8180, and the URLs it prints include that port (on Linux and WSL2 a non-root user cannot check port 80, so the range is used there). Use the URL tdk up prints, or set TDK_HTTP_PORT. A resource named orders-api is served at /api/orders (a trailing -api is dropped); tdk up prints the exact URLs.
Scaffolding a backend and frontend, then listing the stack.
You maintain service.json; TDK generates the local runtime files. A frontend such as services/store/storefront-web has files like these after generation:
services/store/storefront-web/
├── service.json # your service definition
└── .autogenerated/ # TDK writes these files
├── nginx.autogenerated.conf # serves the build and routes API requests
├── Dockerfile.app.autogenerated # local app image
├── .env.frontend.autogenerated # local frontend environment
├── vite.config.frontend.autogenerated.ts
├── tsconfig.autogenerated.json
└── api-client.ts # generated API client
You do not need to write the nginx config, Dockerfile, or a docker-compose.yml for this local stack. tdk up uses Docker and Tilt to start it. The generated-files guide lists the other outputs and explains how regeneration and drift checks work.
If Helm, Compose, or your existing Tilt setup already gives you a working local environment, keep using it. TDK CLI is for engineers managing several services who want a clear local service contract and one command to start the stack.
See how TDK CLI works alongside Helm, the service schema, and the project configuration schema.
Use tdk ui to inspect stacks and resources. Arrow keys or j/k move the
selection; g/G or Home/End jump to the first/last item, and PageUp/PageDown
move one visible page. / searches; navigation letters remain search text
while searching. The selected row stays visible when the terminal is resized.
Install the CLI from npm (requires Node.js 22.12+) or use the prebuilt binary (no Node.js or Bun required):
npm install -g @tdk-landscape/tdk-cli-core
# or install the prebuilt binary
curl -fsSL https://tdk-landscape.github.io/install.sh | shtdk up shop --dry-run previews selected local services and URLs before starting containers. The default starter is Bun/TypeScript; TDK's core role is running local containers through Docker + Tilt, not providing a Node.js application framework. See the one-backend example.
- Your existing Compose or Tilt workflow already gives you a working local environment.
- Helm is your whole development workflow and you do not want local services on Docker.
- You do not want
service.jsonmanifests and generated local configuration.
Set TDK_DEBUG=1 before running tdk up --verbose to include Starlark debug logs in Tilt output.
- CLI command cheat sheet
- Mega cheat sheet: every command and flag
- Documentation index
- Pilot TDK on a real repository
- Running AI agents in TDK
- FAQ for agencies and multi-client teams
- Working alongside Helm
- Scope: local development, and what does not carry over to production
- Gradual adoption: adding TDK to an existing repository
- Troubleshooting: tdk and Tilt error messages and their fixes
- Layout and ownership: services in several repositories
- Local data: reset, seed, snapshot
- Upgrading and version pinning
- Security: network calls, secrets and supply chain
- Pilot scorecard
- Bring-your-own resources
- Configuration and editor schemas
- Generated service files and drift checks
- Runnable one-backend example
- Runnable Python backend example
- Full multi-service example
- Features and license limits
- Honest comparison and known limits
- Public claims registry
- Show HN draft
- Architecture and repository map
- Scale fixture measurements and caveats
- Benchmark report: warm and cold start charts, history (updated on every change to
mainthat affects start-up) - How to run the start-time benchmark
TDK development began on 21 April 2026. The archived, read-only tdk-landscape/tdk
repository records its first commit
("Initial commit: TDK specs, generators, CLI, and standards") from that day. A separate tdk-cli history spanning 21 April to
18 September 2026 was imported into this repository as 306 filtered
commits. Those commits are now ancestors of main; the import did not change the source tree.
This tdk-cli-core repository was created on 19 September 2026, and the @tdk-landscape/tdk-cli-core npm package was first
published on 21 September 2026. Those dates describe the current repository and package, not the start of TDK development.
For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20.2+) and Tilt. Bun 1.2+ is used by the default generated services. TDK selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT to override them. Dev ports listen on 127.0.0.1 only, so other machines on your network cannot reach them. Set TDK_BIND_ADDRESS (for example 0.0.0.0, to test from a phone) to change that; tdk doctor warns when it is a wildcard address. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run tdk doctor to check local readiness (supports --no-ping to skip service health checks and --ping-timeout <ms>). See WSL2 setup.
On native Windows, tdk --version, tdk doctor, and tdk up --dry-run are inspect-only commands. tdk up exits 2 with “Landscape startup needs Ubuntu on WSL2. Native Windows is inspect-only.”
| Capability | Free | Premium |
|---|---|---|
tdk up, scaffold, Traefik, Postgres, Tilt live update, golden layers |
yes | yes |
| Verdaccio, DDD scaffold, Sablier idle stop | no | key |
| Playwright, C4, AGENTS.md | free if generated in-repo | only if the implementation is downloaded with a key |
Core stays free. Premium is a separate key for the extras above; no key required to run tdk up.
Ecosystem map: examples, articles, related tools, and notes live in awesome-tdk-framework. Star this repo (tdk-cli-core) if the CLI is what you run; use the awesome list to browse the rest.
Share: X · Bluesky · Threads · Mastodon · Reddit · Hacker News · Facebook · LinkedIn · Telegram · WhatsApp · Email
Contributions are welcome. Start with CONTRIBUTING.md and the contributor guide. To review pull requests, see Review a pull request. Report security issues using SECURITY.md.
TDK is MIT-licensed; see LICENSE. The license boundary says which code is MIT and which is downloaded with a key.
Project governance: GOVERNANCE.md, MAINTAINERS.md, ADOPTERS.md.