@flisk-sh/flisk
Advanced tools
Go from an empty folder to a running tech stack with one command. Built for agents.
ERP fixture scale run on a clean GitHub-hosted runner (4 vCPU, 15 GB RAM), snapshot from run 39160719471. The live status is in the ERP fixture scale E2E badge above.
English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Türkçe | Tiếng Việt | ไทย | Deutsch | Español | Français | Українська | Polski | Português (Brasil) | العربية | فارسی | Bahasa Indonesia | Italiano | Ελληνικά | മലയാളം
Website · Quickstart · Examples · Awesome Flisk · Demo · Report a bug
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.
Flisk CLI Core bridges the gap. You write the clean web application logic, and Flisk instantly autodetects your stack to generate, link, and orchestrate the local environment for you.
Fastest way (recommended): open the Flisk starter in a ready-to-use environment.
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |  |  |
 |
No vendor lock-in. No tedious plumbing. Run a single command to natively orchestrate 72 different integration tiers including:
Flisk 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
flisk resource bot --type agent --stack shop --yes
flisk resource tools-mcp --type mcp --stack shop --yes
flisk up shop
Agents get durable checkpoint volumes that survive flisk 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.
Flisk CLI — start services on your machine. It is not a deploy and not a Compose file: define each service in service.json, then run flisk up. No Kubernetes is needed on the machine.
Stability: 1.x local dev. Write service.json; Flisk generates the local runtime files. See what Flisk 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. Flisk CLI writes the configuration Tilt uses. Production deployment stays with Helm, Argo CD, or Kustomize.
[!IMPORTANT] Get Flisk from the flisk-sh/flisk repository, the
@flisk-sh/flisknpm package, or the official website. Follow the installation links from these official sources. A similar repository name or copied README does not establish that a download is official.
Quick start · Why Flisk · Examples · Installation · FAQ · Documentation
If Flisk helps you run your local stack, a ⭐ on this repo helps other developers find it.
flisk 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.
service.json per service. Flisk generates the Dockerfile, Traefik routing, and Tiltfile from it. You do not hand-write a docker-compose.yml or nginx.conf.flisk records the generated files and reports drift, so local config stays in sync. See generated files and drift checks.| Capability | docker-compose | Local Kubernetes (kind, minikube) | Plain Tilt | Flisk CLI |
|---|---|---|---|---|
| Scaffold a new service in one command | No | No | No | Yes (flisk resource) |
| Hot reload on file change | Partial (compose watch) | Partial (extra tooling) | Yes | Yes |
| Health-checked startup order | Yes (depends_on: condition: service_healthy) | Yes | Manual configuration | Yes |
| Ingress routing and Postgres included | No | No | No | Yes (Traefik + Postgres) |
| Start only one stack of a large system | Partial (profiles) | Manual | Manual | Yes (flisk up <stack>) |
See the detailed tool comparison for architectural tradeoffs, when each tool is the better choice, and migration workflows.
service.json next to its code.flisk up <stack>. Flisk generates the local runtime files from those manifests: Dockerfiles, Traefik routing, and the Tiltfile.flisk ui to inspect running services, and flisk doctor or flisk config verify to check the environment and generated files.Production deployment stays with your own tools (Helm, Argo CD, or Kustomize).
| You want to | Flisk does | Command |
|---|---|---|
| Start a new project | Creates the project and first services | flisk project --yes |
| Add a service | Writes its service.json and generated files | flisk resource <name> --type backend --stack <stack> --yes |
| Start a whole stack | Starts Postgres, your services, and the routing, and prints the URLs | flisk up <stack> |
| Preview before starting | Shows which services and URLs would start, without containers | flisk up <stack> --dry-run |
| Inspect running services | Opens an interactive terminal dashboard | flisk ui |
| Check your machine | Reports Docker, Tilt, and port readiness | flisk doctor |
| Catch config drift | Compares generated files with what Flisk last wrote | flisk config verify |
| Keep Flisk current | Upgrades the CLI in place | flisk upgrade |
Teams that run flisk up on their own code (listed with their consent in ADOPTERS.md):
Using Flisk too? Tell us or add a row to ADOPTERS.md.
If Flisk saves you time, a ⭐ on this repo helps other developers find it.
There are two ways to get started. Both end with flisk up <stack>.
| Guided scaffolder | Core CLI (manual) | |
|---|---|---|
| Best for | A first run: pick your services and get a ready project | Full control, or adding Flisk to an existing folder |
| Package | create-microservices | @flisk-sh/flisk (this repo) |
Prerequisites. Install these first. The scaffolder checks your machine while it creates the project and stops if something is missing:
Run these commands from the directory where you want the new project folder to be created. The target directory must be new or empty; existing files are never overwritten.
npm install -g @flisk-sh/flisk
npm init create-microservices my-project
cd my-project
flisk up main
npm install -g @flisk-sh/flisk installs the flisk command. Skip it if flisk --version already works.npm init create-microservices my-project asks how many services to create, then each service's name and type (backend, frontend, worker, or mcp).flisk up main starts the stack. main is the default stack name; if you pass --stack <name> to the scaffolder, use that name instead. The scaffolder prints the exact flisk up command when it finishes.The scaffolder creates the project configuration and a skeleton for each service you selected, using Flisk CLI Core. It does not start any containers; flisk up does that.
To skip the prompts and get a default api (backend) and web (frontend):
npm init create-microservices my-project -- --yes
For service types, all options, and non-interactive usage, see the create-microservices README.
[!NOTE] Two similarly named packages exist.
create-fliskis a landing-page app and does not scaffold projects.create-microservicesis the project scaffolder used above.
Use this to create the project and each resource yourself with flisk. Install the CLI first. Preview what a stack will start before any container runs:
flisk up shop --dry-run
Then try the full flow:
mkdir shop && cd shop
flisk project --yes
flisk resource orders-api --type backend --stack shop --yes
flisk up shop
curl http://api.shop.localhost/api/orders/health
flisk 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 flisk up prints, or set TDK_HTTP_PORT. A resource named orders-api is served at /api/orders (a trailing -api is dropped); flisk up prints the exact URLs.
Scaffolding a backend and frontend, then listing the stack.
You maintain service.json; Flisk 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/ # Flisk 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. flisk 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. Flisk CLI is for engineers managing several services who want a clear local service contract and one command to start the stack.
See how Flisk compares to alternative dev tools, how Flisk CLI works alongside Helm, the service schema, and the project configuration schema.
Use flisk 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.
Keep Flisk up to date to get the latest bug fixes:
flisk upgrade
flisk update is an alias for the same command. If you installed with npm, you can also run npm install -g @flisk-sh/flisk@latest. To pin a version or read what changed, see upgrading and version pinning.
Runnable examples show Flisk on real stacks. Start with the smallest one:
| Example | What it shows |
|---|---|
| one-backend | One Bun/TypeScript backend with Postgres |
| one-backend-python | A Python backend in the same local stack |
| one-backend-helm | Working alongside Helm |
| byo | Bringing your own existing resources |
| byo-jobs | Bring-your-own jobs |
| tdk-example | A full multi-service stack |
The repository ships agent skills for common Flisk work, including flisk-doctor (environment checks) and flisk-troubleshoot (fixing flisk and Tilt errors), under .agents/skills. Agents working in this repo also follow AGENTS.md. Use these skills to let your agent check your setup and explain failures instead of guessing at Docker or Tilt configuration.
Install the CLI from npm (requires Node.js 22.12+) or use the prebuilt binary (no Node.js or Bun required):
npm install -g @flisk-sh/flisk
# or install the prebuilt binary
curl -fsSL https://flisk.sh/install.sh | sh
Public npm is the recommended default. To install through GitHub Packages instead, configure registry authentication as described in GitHub Packages installation.
flisk up shop --dry-run previews selected local services and URLs before starting containers. The default starter is Bun/TypeScript; Flisk's core role is running local containers through Docker + Tilt, not providing a Node.js application framework. See the one-backend example.
service.json manifests and generated local configuration.Set TDK_DEBUG=1 before running flisk up --verbose to include Starlark debug logs in Tilt output.
main that affects start-up)Flisk development began on 21 April 2026. The archived, read-only flisk-sh/tdk
repository records its first commit
("Initial commit: Flisk 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 flisk repository was created on 19 September 2026, and the @flisk-sh/flisk npm package was first
published on 21 September 2026. Those dates describe the current repository and package, not the start of Flisk 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. Flisk 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; flisk doctor warns when it is a wildcard address. Flisk supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run flisk doctor to check local readiness (supports --no-ping to skip service health checks and --ping-timeout <ms>). See WSL2 setup.
On native Windows, flisk --version, flisk doctor, and flisk up --dry-run are inspect-only commands. flisk up exits 1 with “Landscape startup needs Ubuntu on WSL2. Native Windows is inspect-only.”
| Capability | Free | Premium |
|---|---|---|
flisk 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 flisk up.
Ecosystem map: examples, articles, related tools, and notes live in awesome-tdk-framework. Star this repo (flisk) 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
No. Flisk runs your services with Docker and Tilt on your machine. It does not need a local cluster such as kind or minikube, and it does not replace Helm, Compose, or your production deployment tools.
No. Core CLI is MIT and needs no key to run flisk up. Premium extras are optional and use a separate key (see the license matrix).
macOS and Linux are supported directly. Windows is supported through WSL2 Ubuntu; native Windows supports CLI inspection only (flisk --version, flisk doctor, and flisk up --dry-run). See Requirements and support and WSL2 setup.
Flisk runs the local stack on your machine. For network calls, secrets, and supply-chain details, see security: network calls, secrets and supply chain.
Yes. If your existing setup already gives you a working local environment, keep using it. See working alongside Helm and gradual adoption for adding Flisk to an existing repository.
Update first; a recent release may already fix it. Run flisk upgrade (also available as flisk update), or:
npm install -g @flisk-sh/flisk@latest
Then run flisk doctor and retry the same task. If the problem persists, open an issue with your Flisk version, operating system, steps to reproduce, and the error output. See upgrading and version pinning and troubleshooting.
Contributions are welcome. Start with CONTRIBUTING.md and the contributor guide. For the project structure, see the architecture and repository map. To review pull requests, see Review a pull request. Report security issues using SECURITY.md.
Flisk 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.
FAQs
Flisk CLI — start services on your machine.
The npm package @flisk-sh/flisk receives a total of 0 weekly downloads. As such, @flisk-sh/flisk popularity was classified as not popular.
We found that @flisk-sh/flisk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.