Flisk

[The Flisk ecosystem: bring an app (Rust, Go, Python, TypeScript, JVM, Ruby, PHP) from a Compose file, a Tiltfile, a Dockerfile or any image; flisk up runs 77 building blocks: 5 languages, 10 web frameworks, 10 API frameworks, 10 resource types, 8 data and AI services, 23 MCP tools and 11 starter projects; export writes render.yaml or wrangler.toml; a radar watches every running part]

What is Flisk?

Flisk is a command-line tool for local development. It runs every part of your app (API, website, workers, AI agents, database) on your computer with one command. Docker is optional: a small app runs as plain local processes, and a bigger one gets containers, one address in front of every part and live reload on Docker and Tilt. Have a docker-compose.yml? flisk import reads it. Otherwise describe each part in a small service.json; for the Docker path Flisk writes the Dockerfiles, the Compose file and the Tiltfile from it, and keeps them in sync. An MCP server lets your AI agent run it too. It does not deploy: production stays with your own tools.

Try it first. One command, nothing to install except Node.js 22.12+, and no Docker needed:

npx @flisk-sh/flisk demo

With Docker running and Tilt installed, that starts the full restaurant demo: six services, Postgres, one gateway and live reload. Without them (or on native Windows), it starts a small menu app as two local processes in about a second and opens it in your browser. You should see the menu at http://localhost:3000, with its API answering at http://localhost:4000/api/menu. flisk down in the demo folder stops either one.

On Windows, the full app runs in Ubuntu on WSL2: follow Start here on Windows.

Want to choose your own stack? Answer a few questions with the arrow keys and Enter, and Flisk writes a project that runs:

npx @flisk-sh/flisk create

It offers every website framework, API language and starter that Flisk's generators know, read from the generators themselves (type to filter a long list), and the default runs on your computer with no Docker, no Tilt and no database: it writes a website and an API with the real flisk resource --local command, then you npm install in each and run flisk up. Pick "I know what I want: let me choose every part" to choose the framework and language yourself, or to add a worker, a queue (NATS, RabbitMQ), Redis, Qdrant, MinIO or an AI agent (those run with Docker and Tilt). The project name comes last and Enter takes my-app; a review shows what will be created and which programs it needs before anything is written. Add --dry-run to see the commands it would run, or flags such as --frontend vue --backend fastify --yes to skip the questions in a script.

Install Flisk with npm install -g @flisk-sh/flisk, then, in a new folder:

mkdir my-shop && cd my-shopflisk project --yesflisk resource orders-api --type backend --stack shop --yesflisk resource shop-web --type frontend --stack shop --yesflisk up shop

That starts an orders API and a storefront behind one gateway, with Postgres and live reload, and prints their URLs. It needs Docker, Tilt, Node.js 22.12+ and Bun 1.2+; flisk doctor says what is missing. A small app can skip Docker and run as local processes.

Two ways in: flisk project starts a new app from scratch (above); flisk import starts from an app you already have. Already have a Compose file? npx @flisk-sh/flisk import . && npx @flisk-sh/flisk up (add --dry-run to import to preview).

[Four flisk commands create a project, an API, and a website, then start them]

One small file per service

flisk resource wrote a service.json for each part. This is the whole file for the orders API, and the only configuration you edit for it:

{  "$schema": "https://flisk.sh/schema.service.json",  "schemaVersion": 1,  "appName": "orders-api",  "appType": "backend",  "stack": "shop",  "port": 4000,  "healthCheckPath": "/health"}

From it Flisk writes the Dockerfile, the Compose entry, the gateway route, the health check and the DATABASE_URL, and refuses to start if one of those files was edited by hand. Every field · Everything Flisk writes

Already have a docker-compose.yml?

flisk import . writes one service.json per Compose service and keeps its ports, names and env values:

flisk import .flisk up

On Windows: a Compose app runs its services as containers, so do both steps inside Ubuntu on WSL2, not in PowerShell. Clone the app into your Ubuntu home folder (~/, not /mnt/c or D:\), turn on Docker Desktop's WSL integration for Ubuntu, and install Node and Tilt in Ubuntu: Start here on Windows.

_{A plain Compose app (a Node API and Postgres) answered through Flisk's router 49 s after flisk import on a clean Ubuntu CI runner, images pulled and built from scratch, install not counted (run, claims). CI repeats it on every pull request.}

Rather ask your AI helper? It runs these commands for you: copy a prompt. Never written code? Start here, step by step · Words you'll see

Key features

• One service.json per service. Flisk generates the Dockerfile, the Compose entry, the Traefik routes, the health check and the Tiltfile from it. You do not hand-write a docker-compose.yml or nginx.conf.
• One command, one address. flisk up starts Postgres, your services and a local gateway, starts services in health-checked dependsOn order, and prints a *.localhost URL for each.
• Hot reload while you code. Tilt live-updates a container when you save its files; there is no rebuild step.
• Wired for you. DATABASE_URL, the API URL your frontend calls, and missing secrets such as JWT_SECRET are generated and injected, never copied by hand.
• Generated files you can check. Flisk records what it wrote, refuses to start when a generated file was edited by hand, and flisk config verify reports drift (generated files and drift checks).
• Built for AI helpers. flisk mcp gives Claude Code, Codex, Cursor and other agents 23 tools, and flisk project adds the Flisk skills and an AGENTS.md.
• Runs AI agents too. Agent services get durable checkpoints, sticky x-session-id routing, and /health and /ready checks (below).
• No Kubernetes; no Docker for small apps. Docker and Tilt run the stack without a local cluster such as kind or minikube, and services that each declare a command run as plain local processes.
• Quick to start. With warm image layers, a one-backend stack is healthy in 12.8 to 13.8 seconds (timing notes). An 8-service stack settles in 32 to 42 seconds warm and about 4.5 minutes on its first cold build (benchmark).
• Free core. The CLI is MIT and needs no key to run flisk up; Premium extras are optional (license matrix).

Is Flisk right for your team?

Not sure Flisk fits? Answer three questions for a plain-English score and the reasons behind it, or use the calculator on flisk.sh.

Trusted by

_{Teams that run flisk up on their own code, listed with their consent. See all adopters or add yours.}

Use Flisk with your AI agent

AI helpers are good at writing the app and bad at the setup around it: every time one rewrites a Dockerfile, a Tiltfile or an nginx.conf by hand, something breaks, and you pay in time and tokens to fix it. Flisk writes that setup the same way every time, so you and your helper stick to the app.

[Claude Code, running in the Warp terminal, builds a small online shop with Flisk and runs it locally]

_{An illustrative Claude Code session in the Warp terminal. The Flisk commands, their output, and the URLs Flisk prints come from a real run.}

Install Flisk, then paste the prompt into Claude Code, Codex, Cursor or any other AI helper that can run commands:

npm install -g @flisk-sh/flisk

Build me a small online shop with a storefront and an orders API, and run it on my laptop with Flisk.

The helper creates the project, adds each part and starts it, then gives you the links to open. If something is missing, flisk doctor says what, in plain words.

Use Flisk to add a backend service called payments-api to my shop stack, then start the stack and give me the URLs.

Use Flisk to scaffold an AI agent, an MCP tools server, and a database in one stack called shop, then start it and tell me how to talk to the agent.

Run flisk doctor, explain every problem in plain words, and fix what you can. Then start my stack with flisk up.

Use flisk status to tell me which services are running, which are unhealthy, and what URL each one has.

Stop my Flisk stack with flisk down and confirm nothing is left running.

Pick your agent

Each helper installs a little differently; pick yours for the exact steps. Already have a project? flisk connect claude (or cursor, codex) adds the flisk mcp server (23 tools) and the Flisk skills where that agent reads them; add --dry-run to see the files first. What the agent can then do: Flisk for AI agents.

curl -fsSL https://claude.ai/install.sh | bashnpm install -g @flisk-sh/flisk

Any other agent that can run terminal commands works too: point it at AGENTS.md, or connect it to flisk mcp, which runs an MCP server over stdio. flisk project adds the Flisk skills (build a stack, recipes for a shop, a SaaS, an AI agent and a blog, doctor, up, resource, status, troubleshoot; source in .agents/skills) and an AGENTS.md to your project, so the agent checks your setup and explains failures instead of guessing at Docker or Tilt configuration. More prompts by category are in the prompt gallery.

No terminal at hand? Open the Flisk starter in GitHub Codespaces or Gitpod, or pick another one-click option.

Run your AI agents next to your services

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 stackflisk resource bot --type agent --stack shop --yesflisk resource tools-mcp --type mcp --stack shop --yesflisk 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.

Prerequisites (install once)

Two ways to run. A project whose services each declare a command runs them as local processes: you need only Flisk and your app's runtime (simplest path). A database, one gateway URL for every service, or the same container you deploy need Docker and Tilt. flisk doctor checks only what your project uses.

Set up your machine. Pick your system:

curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh \  | bash

npm install -g @flisk-sh/fliskflisk doctor

Installation

Install the CLI with npm, with Bun, as a prebuilt binary that needs no Node.js or Bun, or run it from its container image:

npm install -g @flisk-sh/flisk

Update later with flisk upgrade (or its alias flisk update), or npm install -g @flisk-sh/flisk@latest. To pin a version or read what changed, see upgrading and version pinning.

[!IMPORTANT] Get Flisk from the flisk-sh/flisk repository, the @flisk-sh/flisk npm 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

The commands under What is Flisk? are the whole quick start, once the prerequisites are in place. This section is the long version: the other ways to start, what to expect, and what Flisk writes. Never used a terminal? Start here instead.

Pick how to start

Four ways to get your app running: the simplest one, a one-command demo, a project you set up by hand, and a guided setup that asks you questions. The simplest is below; each tab opens its own page.

npm install -g @flisk-sh/flisk

{  "schemaVersion": 1,  "appName": "api",  "appType": "backend",  "command": "node server.js",  "port": 4000,  "healthCheckPath": "/health"}

{  "schemaVersion": 1,  "appName": "web",  "appType": "frontend",  "command": "node server.js",  "port": 3000,  "dependsOn": ["api"]}

flisk up

Verify it works

For the shop at the top of this page, flisk up shop first lists what it starts and where:

Starting 2 services from stack "shop"...  - orders-api  - shop-web
🌍 Frontend URLs:  - shop-web: http://app.my-shop.localhost/shop-web/health
🔧 Backend API URLs:  - orders-api: http://api.my-shop.localhost/api/orders/healthHost ports: HTTP 80, HTTPS 443, Postgres 15432

Then Tilt builds and starts the containers, and flisk up ends with Flisk is up. and the Tilt dashboard address, http://localhost:10350, where each service turns green when it is healthy. Your host ports can differ: when 80 or 5432 is busy, Flisk picks a free one and the URLs include it. flisk down stops everything. Every command you will use next is under Commands.

Troubleshooting

Full troubleshooting: docs/troubleshooting.md

Set FLISK_DEBUG=1 before running flisk up --verbose to include Starlark debug logs in Tilt output.

What Flisk writes for you

You write one service.json per service. For the two-service shop above, Flisk writes the rest at three levels: the project, the stack, and each service.

my-shop/├── .env                                              # generated DB_PASSWORD and JWT_SECRET├── .flisk/│   ├── project.json                                  # project settings (yours to edit)│   └── .flisk-out/                                   # PROJECT LEVEL│       ├── Tiltfile                                  # what Tilt runs│       ├── docker-compose.traefik.yml                # local gateway, bound to 127.0.0.1│       ├── golden-layers.Dockerfile                  # shared base image layers│       ├── TILT_TECH_STACK.star                      # tech stack settings│       ├── TILT_RESOURCE_DEFAULTS.star               # service defaults│       ├── spec.master                               # project spec by stack│       └── flisk-cli-ext/                            # pinned copy of the Flisk engine├── shared-platform-engineering/│   └── docker-templates/                             # container entrypoint scripts└── services/    ├── platform/database-management/    │   └── docker-compose.yml                        # Postgres 16    └── shop/        ├── .autogenerated/                           # STACK LEVEL        │   └── docker-compose.app.autogenerated.yml  # every service in the stack        ├── orders-api/        │   ├── service.json                          # you write this        │   └── .autogenerated/                       # SERVICE LEVEL: 14 files        └── shop-web/            ├── service.json                          # you write this            └── .autogenerated/                       # SERVICE LEVEL: 18 files

The stack's Compose file is the part you would otherwise write by hand. For these two services it holds the image builds, environment, 33 Traefik routing labels, four networks, health checks, and CPU and memory limits. An excerpt:

orders-api:  environment:    - DATABASE_URL=postgresql://my_shop:${DB_PASSWORD}@my_shop_postgres:5432/my_shop_shop?schema=public    - JWT_SECRET=${JWT_SECRET:?JWT_SECRET is not set. Run `flisk up` ...}  labels:    - "traefik.http.routers.orders-api-project.rule=Host(`api.my-shop.localhost`) && PathPrefix(`/api/orders`)"    - "traefik.http.middlewares.orders-api-strip-prefix-project.stripprefix.prefixes=/api/orders"    - "traefik.http.services.orders-api.loadbalancer.healthcheck.path=/health"  healthcheck:    test: ["CMD", "curl", "-f", "--max-time", "5", "http://localhost:4000/health"]

Secrets come from the project .env by default: flisk project generates a random database password and JWT secret, and .env is added to .gitignore. Set FLISK_SECRET_PROVIDER=infisical to read secrets from Infisical instead (environment).

shop-web/.autogenerated/├── Dockerfile.app.autogenerated               # app image├── Dockerfile.app.autogenerated.dockerignore  # build context├── nginx.autogenerated.conf                   # serves the build, routes API requests├── vite.config.frontend.autogenerated.ts      # dev server├── vite.config.build.autogenerated.ts         # production build├── tsconfig.autogenerated.json                # TypeScript, host├── tsconfig.docker.autogenerated.json         # TypeScript, container├── .npmrc.autogenerated                       # package registry, host├── .npmrc.docker.autogenerated                # package registry, container├── bunfig.autogenerated.toml                  # Bun settings, host├── bunfig.docker.autogenerated.toml           # Bun settings, container├── .env.frontend.autogenerated                # frontend environment├── env.ts                                     # API URL for your imports├── api-client.ts                              # client for the frontend's API route├── api-index.ts                               # re-exports the client and URL├── service.yaml                               # Tilt's projection of service.json├── validation-report.autogenerated.json       # preflight validation result├── AGENTS.md                                  # tells coding agents not to edit here└── .flisk-contract/                           # snapshots for drift checks

orders-api/.autogenerated/├── Dockerfile.app.autogenerated               # app image├── Dockerfile.app.autogenerated.dockerignore  # build context├── vite.config.backend.autogenerated.ts       # server build├── prisma.config.autogenerated.ts             # database client├── tsconfig.autogenerated.json                # TypeScript, host├── tsconfig.docker.autogenerated.json         # TypeScript, container├── .npmrc.autogenerated                       # package registry, host├── .npmrc.docker.autogenerated                # package registry, container├── bunfig.autogenerated.toml                  # Bun settings, host├── bunfig.docker.autogenerated.toml           # Bun settings, container├── .env.backend.autogenerated                 # backend environment├── service.yaml                               # Tilt's projection of service.json├── validation-report.autogenerated.json       # preflight validation result├── AGENTS.md                                  # tells coding agents not to edit here└── .flisk-contract/                           # snapshots for drift checks

You never write an nginx config, a Dockerfile, a Compose file, or Traefik labels for this stack. flisk up regenerates these files when service.json changes and refuses to start if one was edited by hand. Python, Go, and Rust services, and optional features such as Playwright, get their own sets; the generated-files guide lists them and explains the drift checks.

See how Flisk compares to alternative dev tools, how Flisk CLI works alongside Helm, the service schema, and the project configuration schema.

Commands

The commands you will use every day:

Commands take --help, and --json prints one JSON object for scripts and agents (machine-readable output). The same actions are MCP tools through flisk mcp. Every command and flag: cheat sheet.

Flisk works with:

• Runtimes & Frameworks: Bun, Node, Python, Go, Rust, React, Vue, Svelte, Elysia, Fastify, NestJS
• Databases & Tooling: Prisma, Drizzle, Atlas, Dbmate
• Messaging & Gateway: NATS, Traefik

Configuration

You edit three kinds of files; Flisk writes everything else and checks it for hand edits.

Flisk selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres, and dev ports listen on 127.0.0.1 only, so other machines on your network cannot reach them. These environment variables change that and more:

Editor autocomplete and validation for both JSON files: configuration and editor schemas.

How Flisk works

1. Describe each service in a service.json next to its code.
2. Run flisk up <stack>. Flisk generates the local runtime files from those manifests: Dockerfiles, Traefik routing, and the Tiltfile.
3. Docker runs the containers and Tilt watches them. Edit code and the containers live-update. Use flisk ui to inspect running services, and flisk doctor or flisk config verify to check the environment and generated files.

Everything is wired together, and stays in sync

You do not connect services by hand. Flisk derives each connection from the same service.json files and regenerates it when they change.

See how flisk up works for the full startup sequence.

Why Flisk CLI?

How Flisk compares, in 10 categories with two tools each. Pick a tab:

Docker Compose and Tilt are tools developers use to start the parts of an app on their computer. Compose runs containers from a YAML settings file you write. Tilt watches your files and live-updates the running app as you save them, from a Tiltfile you write. Flisk writes both files for you from one small service.json per service (per part of your app), then runs Tilt.

Where they are stronger

• Compose is the simpler choice for two or three services you already containerized, and it needs no Tilt.
• Tilt gives full control when you are happy to write and maintain a Tiltfile, and it also targets Kubernetes.

Use them together. Flisk generates a Compose file and a Tiltfile and runs them with Docker and Tilt, so the generated files stay readable with flisk config explain.

See the detailed tool comparison for architectural tradeoffs, when each tool is the better choice, and migration workflows.

Examples

Runnable examples show Flisk on real stacks. Start with the smallest one:

When not to use Flisk

• 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.json manifests and generated local configuration.

Requirements and support

For the Docker + Tilt path, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20.2+) and Tilt. Bun 1.2+ is used by the default generated services. Ports and other settings: Configuration.

Flisk supports macOS, Linux, and Windows. On native Windows, flisk demo and projects whose services each declare a command run as local processes; the Docker stack runs through WSL2 Ubuntu, and flisk up on a Docker project exits 1 with “Landscape startup needs Ubuntu on WSL2.” See the Windows & WSL2 guide for the recommended setup, prerequisites, verification steps, and troubleshooting.

Roadmap

For the next 12 months Flisk plans to keep 1.x stable (flisk up, scaffolding, generated files and flisk config verify stay backward compatible), keep the core free, keep Windows and WSL2 working, keep hardening the supply chain, keep the docs current, and add maintainers. It does not plan to deploy to production or to target Kubernetes. The full plan, and how to propose a change: ROADMAP.md.

License matrix

Core stays free. Premium is a separate key for the extras above; no key required to run flisk up.

Stability: 1.x.

FAQ

npm install -g @flisk-sh/flisk@latest

Docs

• Flisk 101: a 13-lab course for beginners
• CLI command cheat sheet
• Mega cheat sheet: every command and flag
• Documentation index
• Pilot Flisk on a real repository
• Running AI agents in Flisk
• FAQ for agencies and multi-client teams
• Working alongside Helm
• Scope: local development, and what does not carry over to production
• Gradual adoption: adding Flisk to an existing repository
• Troubleshooting: flisk 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
• Tool comparison: docker-compose, Tilt, Skaffold, DevSpace, kind
• Honest comparison and known limits
• Public claims registry
• Start in one click: hosted starters and deploy prompts
• Project history
• Architecture and repository map
• Scale fixture measurements and caveats
• Benchmark report: warm and cold start charts, history (updated on every change to main that affects start-up)
• How to run the start-time benchmark

Community

[Flisk on Product Hunt] [flisk-sh%2Fflisk | Trendshift]

Ecosystem map: examples, articles, related tools, and notes live in awesome-flisk-framework.

Contributing and license

Contributions are welcome. First step: say hello on Discord, tell us what you want to work on, and we will point you to a good first task. Then 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.

Contributors

Thank you to everyone who has shipped code, docs, and fixes to Flisk since July 2026. Every merged change makes the local stack better for the next developer.

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.

[flisk] Using Flisk in Slack or Discord? Get the Flisk green thunder emoji (SVG and PNG, MIT).