Flisk App Builder
OfficialThis MCP server lets an AI agent inspect, scaffold, configure, run, and troubleshoot a local Flisk multi-service development stack.
Check host/project readiness (
doctor,runtime_check,project_info) and list templates, stacks, resources, agents, and service URLs.Create or clone projects (
project_init), importdocker-compose.ymlservices (project_import), scaffold resources (resource_create), add tools (tool_add), and assign resources to stacks (stack_assign).Start/stop stacks (
up,down), inspect live status (status), read logs (logs), restart resources (resource_restart), and run one-off commands in a resource environment with confirmation (resource_run).Inspect AI agent resources and their sessions/checkpoints (
agent_list,agent_sessions).Verify, explain, and regenerate generated config files (
config_verify,config_explain,config_regenerate) and write an eject plan (project_eject).It manages local development only; it does not deploy to production or create cloud resources.
Imports existing docker-compose.yml services into Flisk service definitions and generates/syncs Dockerfiles, Compose entries, and Tiltfiles for running local stacks with Docker.
Runs a local PostgreSQL instance as part of a Flisk stack, automatically injects DATABASE_URL into services, and supports PostgreSQL-backed agent session checkpoint durability.
Flisk: local development for multi-service apps, started with one command
MIT · no telemetry · releases signed with Sigstore, and how to check one · what Flisk does not do · security notes · support terms · maintainers · due diligence
What is Flisk? · Key features · Quick start · Commands · Configuration · With your AI agent · FAQ · Docs
👋 Welcome · 欢迎 · 歡迎 · ようこそ · 환영합니다 · Bienvenue · Bienvenido · Bem-vindos · Willkommen · Benvenuti · Bun venit · أهلًا · Hoş geldiniz · Ласкаво просимо · Witamy · خوش آمدید · Selamat datang · Chào mừng · ยินดีต้อนรับ · Καλώς ήρθατε · സ്വാഗതം
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@latest demoWith 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 createIt 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.
Want a website, an API and a Postgres database that already work together? npx @flisk-sh/flisk create myapp --starter next-postgres (or flisk project next-postgres --path myapp) writes a Next.js page with an add, tick and delete list, an Express API and a migrator that creates and seeds the table; then cd myapp && flisk up. It needs Docker.
Every starter — including launch, portal and fullstack — is in the starters table, with a one-line description, its Docker requirements and an example command.
Install Flisk with npm install -g @flisk-sh/flisk, then, in a new folder:
mkdir my-shop && cd my-shop
flisk project --yes
flisk resource orders-api --type backend --stack shop --yes
flisk resource shop-web --type frontend --stack shop --yes
flisk up shopThat 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).
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 upOn 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
Related MCP server: Cerebro MCP
Key features
One
service.jsonper service. Flisk generates the Dockerfile, the Compose entry, the Traefik routes, the health check and the Tiltfile from it. You do not hand-write adocker-compose.ymlornginx.conf.One command, one address.
flisk upstarts Postgres, your services and a local gateway, starts services in health-checkeddependsOnorder, and prints a*.localhostURL 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 asJWT_SECRETare 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 verifyreports drift (generated files and drift checks).Built for AI helpers.
flisk mcpgives Claude Code, Codex, Cursor and other agents 24 tools, andflisk projectadds the Flisk skills and anAGENTS.md.Runs AI agents too. Agent services get durable checkpoints, sticky
x-session-idrouting, and/healthand/readychecks (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
commandrun 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
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.
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/fliskBuild 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.
Add a service to a project you already have
Use Flisk to add a backend service called payments-api to my shop stack, then start the stack and give me the URLs.Build an AI agent with tools and a database
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.Something is not working
Run flisk doctor, explain every problem in plain words, and fix what you can. Then start my stack with flisk up.See what is running
Use flisk status to tell me which services are running, which are unhealthy, and what URL each one has.Stop everything
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, gemini) adds the flisk mcp server (24 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 | bash
npm install -g @flisk-sh/fliskThen start Claude Code by typing claude in your project folder, and paste the prompt above. For developers: flisk project writes the Flisk skills to .claude/skills/, which Claude Code loads. To let Claude Code drive Flisk through MCP tools, run claude mcp add --scope project flisk -- flisk mcp. Windows install, the .mcp.json file and the AGENTS.md tip: full Claude Code setup.
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 stack
flisk resource bot --type agent --stack shop --yes
flisk resource tools-mcp --type mcp --stack shop --yes
flisk up shopAgents 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)
Tool | Version | Install | Needed for |
Your app's runtime | whatever your app uses | Node.js, Python, Go, Bun, ... | Every path: it runs your code |
Node.js | 22.12+ | npm install ( | |
Docker | Engine 25+, Compose 2.20.2+ | Docker + Tilt path only | |
Tilt | 0.25+ | macOS/Linux: | Docker + Tilt path only |
Bun | 1.2+ | macOS/Linux: | Bun install ( |
Two ways to run. A project whose services each declare a
commandruns 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 doctorchecks only what your project uses.
Set up your machine. Pick your system:
Get your Mac ready once. Paste each grey box into the terminal (press Cmd+Space, type Terminal, press Enter) and press Enter.
1. Node.js 22.12+ from nodejs.org, plus your app's own language if it is not JavaScript. That is all a small app needs: the simplest path.
2. Only for bigger apps (a database, one address in front of every part, or the same container you deploy): start Docker Desktop, OrbStack, Colima or Kiri, and install Tilt:
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh \
| bash3. Install Flisk and check your Mac:
npm install -g @flisk-sh/flisk
flisk doctorflisk doctor checks only what your project uses and prints a fix for anything missing. Full steps: macOS setup.
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/fliskThis downloads Flisk with npm, which comes with Node.js 22.12+. Check it with flisk --version: it prints a version number. Update later with flisk upgrade. Pinning a version and uninstalling: install with npm.
For developers: public npm is the recommended default; to install through GitHub Packages instead, configure registry authentication as described in GitHub Packages installation.
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.
Get Flisk from theflisk-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.
Run your app on your own computer with one command, without Docker. This path fits an app made of a few parts that each start with one command, for example a back end (an API), a website and a worker. You need only Flisk and the program that runs your code, such as Node.js.
For developers: each service runs as a local process. You need only Flisk and your app's runtime.
1. Install Flisk. Paste this into your terminal and press Enter:
npm install -g @flisk-sh/flisk2. Describe each part. Put a small settings file called service.json in each part's folder (next to each service). It tells Flisk the part's name, the command that starts it and the port it listens on. This one is for the back end:
{
"schemaVersion": 1,
"appName": "api",
"appType": "backend",
"command": "node server.js",
"port": 4000,
"healthCheckPath": "/health"
}This one is for the website. "dependsOn": ["api"] means "start the back end first":
{
"schemaVersion": 1,
"appName": "web",
"appType": "frontend",
"command": "node server.js",
"port": 3000,
"dependsOn": ["api"]
}3. Start everything. In the terminal, go to your project folder and run:
flisk upWhat you will see: Flisk starts the API, waits until it answers, then starts the website. It prints both URLs (the web addresses to open in your browser; they are localhost links, so only you can see them). Each line of output starts with the name of the part that wrote it. If a part crashes, Flisk starts it again.
To stop, press Ctrl+C (hold Control and press C), or run flisk down. No Docker, no Tilt, no generated files. See Run your app without Docker for every field, and for when to switch to the full stack with a database and one gateway URL (one web address for every part).
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/health
Host ports: HTTP 80, HTTPS 443, Postgres 15432Then 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
Issue | Fix |
| Run the fix commands it prints, then retry |
Port 80/5432 in use |
|
Docker not running | Start Docker Desktop / |
Windows native | Local processes and |
| Run |
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 filesThe 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`) && (Path(`/api/orders`) || 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. The free CLI also accepts FLISK_SECRET_PROVIDER=infisical, but it has no Infisical client: it leaves the secret names to an external or premium bridge and injects nothing, warning about each required secret that will be empty (environment). Any other value is a usage error.
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 checksorders-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 checksA stack with a database migrator also gets docker-compose.migrator.autogenerated.yml in the stack folder, and the migrator gets its own Dockerfile.migrator.autogenerated.
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:
You want to | Flisk does | Command |
Pick a stack with a few questions | Asks what you are building and writes a project that runs (on your computer by default) |
|
Start a new project | Creates the project and first services |
|
Add a service | Writes its |
|
Start a whole stack | Starts Postgres, your services, and the routing, and prints the URLs |
|
Preview before starting | Shows which services and URLs would start, without containers |
|
Inspect running services | Opens an interactive terminal dashboard |
|
Check your machine | Reports Docker, Tilt, and port readiness |
|
Catch config drift | Compares generated files with what Flisk last wrote |
|
Read one service's logs | Prints its recent log lines |
|
Restart one service | Restarts it in the running stack |
|
Stop everything | Stops every service in the stack |
|
Keep Flisk current | Upgrades the CLI in place |
|
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.
File | What it holds | Reference |
| Name, type, stack, port, health check, | |
| The project name and which stacks each phase enables; | |
| Secrets such as |
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:
Variable | What it does |
| Pin the host port for the gateway (HTTP, HTTPS) or Postgres |
| The address dev ports listen on, |
|
|
| The Tilt UI port, 10350 by default |
|
|
Editor autocomplete and validation for both JSON files: configuration and editor schemas.
How Flisk works
Describe each service in a
service.jsonnext to its code.Run
flisk up <stack>. Flisk generates the local runtime files from those manifests: Dockerfiles, Traefik routing, and the Tiltfile.Docker runs the containers and Tilt watches them. Edit code and the containers live-update. Use
flisk uito inspect running services, andflisk doctororflisk config verifyto 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.
When you... | Flisk updates |
Add a service with | It is discovered automatically and its stack is enabled on the next |
Edit a | The Dockerfile, Compose entry, Traefik labels, and nginx config are regenerated on the next |
Edit your code | Tilt live-updates the running container. No rebuild step. |
Add a backend route | Frontends already point at the API through generated |
Add a database or a second backend |
|
Run on a project with an older or missing | Missing secrets such as |
Declare | Services start in health-checked order. |
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.
Docker Compose | Tilt | Flisk | |
Scaffold a new service in one command | Partial ( | No | Yes ( |
Hot reload on file change | Partial ( | Yes ( | Yes (generated Tilt |
Health-checked startup order | Yes ( | Yes ( | Yes (from |
Gateway URL per service and Postgres included | No (you add them) | No (you add them) | Yes (Traefik |
Start one stack of a large system | Partial (profiles) | Yes ( | Yes ( |
Config you write by hand |
|
|
|
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:
Example | What it shows |
One Bun/TypeScript backend with Postgres | |
A Python backend in the same local stack | |
Working alongside Helm | |
Bringing your own existing resources | |
Bring-your-own jobs | |
A full multi-service stack |
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.jsonmanifests and generated local configuration.
Requirements and support
For the Docker + Tilt path, install Docker (Desktop, OrbStack, Colima, or Kiri; 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
Capability | Free | Premium |
| 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.
Stability: 1.x.
FAQ
Yes, if you build with an AI helper like Claude Code, Codex or Cursor. You describe the app; the helper writes it and uses Flisk to run it on your computer. Start here walks you through it step by step, and Words you'll see explains the terms. You will paste a few commands into a terminal, but you do not need to write any code.
The Flisk command-line tool is free and open source (MIT); optional Premium extras need a key (see the license matrix). Your AI helper has its own plans and prices. Bigger apps also use Docker Desktop, which is free for personal use and small companies.
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. On Windows, flisk demo and local-process projects run natively; the Docker stack runs through WSL2 Ubuntu, and native Windows can still inspect it (flisk doctor, flisk up --dry-run). See Requirements and support and the Windows & WSL2 guide for the recommended setup, prerequisites, verification steps, and troubleshooting.
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@latestThen 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.
Docs
Scope: local development, and what does not carry over to production
Troubleshooting: flisk and Tilt error messages and their fixes
Tool comparison: docker-compose, Tilt, Skaffold, DevSpace, kind
Benchmark report: warm and cold start charts, history (updated on every change to
mainthat affects start-up)
Community
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.
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.
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.
Top contributors (10+ merged PRs, from the Hall of fame):
Everyone else:
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, TRUST.md (due diligence).
Using Flisk in Slack or Discord? Get the Flisk green thunder emoji (SVG and PNG, MIT).
Available Tools
24 toolsagent_listARead-only
List AI agent resources (appType: 'agent') in the project with their stack, runtime, durability and port. Read-only. Use resource_list for every resource type, and agent_sessions to inspect one agent's sessions. Set projectPath when the MCP server is not running from the project root.
Inputs: stack, projectPath.
agent_sessionsARead-only
List the sessions of a running AI agent resource (id, last activity, status, checkpoint size), or read one session's checkpoint when sessionId is set. Set projectPath when the MCP server is not running from the project root.
Inputs: resource (required), sessionId, projectPath.
config_explainARead-only
Explain one project file: whether Flisk generated it or the user owns it, its source, whether it is edited now, whether editing it blocks up, and what to edit instead. Run it before editing a file you did not write. Set projectPath when the MCP server is not running from the project root.
Inputs: file (required), projectPath.
config_regenerateADestructiveIdempotent
Regenerate the master config files in .flisk/.flisk-out/ from .flisk/project.json. A dry run by default, which returns the planned changes as data.changes (each file's status and lineDiff) with data.hasChanges; set dryRun to false to write them and get the same list, which discards hand edits in those generated files. Set projectPath when the MCP server is not running from the project root.
Inputs: dryRun, projectPath.
config_verifyARead-only
Check that the generated files match .flisk/project.json and that every service.json is valid. Returns data.valid, data.errors, data.warnings and data.diffs; a drifted generated file is fixed with config_regenerate. Set projectPath when the MCP server is not running from the project root.
Inputs: projectPath.
doctorARead-only
Check whether this machine can run the Flisk stack (Docker, Tilt, ports). Read-only. Optionally set projectPath to include checks for a specific Flisk project. Returns data.ready and data.host.canUp; run it before up. For the state of a running stack use status; for whether generated files are consistent use config_verify.
Inputs: noPing, projectPath.
downADestructiveIdempotent
Stop the running stack, optionally selecting its project with projectPath. It stops the running services and does not edit the project's files. Use status first to see whether a stack is running, set dryRun to preview, and start it again with up.
Inputs: dryRun, projectPath.
logsARead-only
A bounded snapshot of recent logs from the running stack (default the last 200 lines, at most 10000), returned as text. Read-only: reading with a cursor writes nothing. Not a stream: every JSON line has a seq, the response carries data.nextCursor, and passing that value back as after returns only newer lines (an unchanged log gives no lines and the same cursor; a cursor older than the retained log returns the oldest available lines with data.truncated: true). Optionally select the project with projectPath. After a failed up, call it first with unhealthy: true to read only the failing or still-starting services. Otherwise use status first to find which service is failing, then pass services to narrow the output and source runtime to skip image build output and read why it failed.
Inputs: tail, after, since, source, +3 more.
network_listARead-only
The Traefik URL of every frontend and API service, with its base path, port and whether it answers (running, stopped). Read-only. Use it to find where to open a service; use status for full readiness. Set projectPath when the MCP server is not running from the project root.
Inputs: stack, projectPath.
project_ejectAIdempotent
Write EJECTED.md with flisk eject --json: it lists the generated Tilt files and how to run the stack with plain Tilt, and copies, moves or deletes nothing. It changes the project, so it is refused unless confirm is true; dryRun returns the plan (data.generatedFiles, data.created) without confirm. Set projectPath when the MCP server is not running from the project root.
Inputs: dryRun, confirm, projectPath.
project_importADestructive
Import the services in a directory's root docker-compose.yml as bring-your-own service.json files with flisk import --json, which runs the pinned flisk-import from npm (the first run needs network access). It writes without asking: set dryRun to get the plan only, and force to overwrite an existing service.json (force needs confirm: true unless dryRun is set). Returns data.written and the importer's output. Set projectPath when the MCP server is not running from the project root.
Inputs: dir, force, dryRun, confirm, +1 more.
project_infoARead-only
Project root, whether the generated master files exist (data.configured, data.missingFiles), and resource and stack counts. Read-only; a quick first call to learn whether a folder is a configured Flisk project. Use config_verify to check that the generated files match, and status for the running stack. Set projectPath when the MCP server is not running from the project root.
Inputs: projectPath.
project_initA
Create a Flisk project with flisk project --yes: in projectPath (an existing directory; default the server's directory) write .flisk/project.json and generate its files, or, with template, clone a starter project into a new directory there (then call project_init again with projectPath set to the clone to configure it). Inside an existing project it refreshes that project's generated files instead and never overwrites its project.json. Returns the command's text output.
Inputs: path, template, agentSkills, projectPath.
project_templatesARead-only
List the starter templates project_init can clone (data.templates): each one's key, repo, description and what it needs to run (needs), plus the ref it checks out when pinned to a commit. Read-only; the same rows as flisk project --list --json. Pass a key as project_init's template.
Inputs: no named parameters.
resource_createADestructive
Scaffold a new service (service.json, Dockerfile, source and a test) with flisk resource <name> --yes, or register an existing directory that already has a service.json. Returns the command's text output. Without stack it uses the only existing stack or main, and fails when several stacks exist. Do not call it again for a resource that already exists: that rewrites its service.json and can assign it a new port (check with resource_list first). Call up afterwards to start it. Set projectPath when the MCP server is not running from the project root.
Inputs: name (required), port, type, local, +7 more.
resource_listARead-only
List the selected project's services (resources) with their stack, type, port and project-relative folder path, whether or not they are running. Read-only. Use status for live state, stack_list to group them by stack and agent_list for agents only. Set projectPath when the MCP server is not running from the project root.
Inputs: stack, projectPath.
resource_restartA
Restart one running resource in the stack along with any active container resources that transitively declare sidecarOf on it (Flisk-generated Compose containers restart without rebuilding their image; local-process resources of a project that runs without Tilt are restarted by the run that supervises them (its .env is re-read, only that service is stopped and started, and the result says whether it is ready, failed with its own output, or still starting); other non-container resources and projects using an imported Tiltfile fall back to tilt trigger); unrelated resources are not touched. It needs a running stack: start one with up. Set rebuild to true for a full Tilt update (rebuild the image and recreate the container, which re-reads the project .env). Names come from resource_list. Set projectPath when the MCP server is not running from the project root.
Inputs: rebuild, resource, projectPath, waitSeconds.
resource_runADestructive
Run a one-off command (a seed script, a migration, a status check) with the environment one resource has in the stack, and return its exit code, stdout and stderr (the last 64 KB of each; values from the project's .env files are masked). It runs any command, so it is refused unless confirm is true: ask the user first. A container resource must be running (start it with up); a local-process resource runs from its folder. No input is passed. Names come from resource_list. Set projectPath when the MCP server is not running from the project root.
Inputs: command (required), resource (required), confirm, projectPath.
runtime_checkARead-only
Read-only. Check that the installed Flisk CLI has its bundled runtime assets (engine, templates). Returns ok, assetRoot and what is missing; a source checkout reports ok: false because the assets exist only in a packaged install. projectPath is optional: a project-local install under its node_modules is checked too.
Inputs: projectPath.
stack_assignAIdempotent
Assign resources that have no stack yet to a stack (writes stack into their service.json). A resource already in a stack is refused unless move is true, which moves it out of its current stack. Returns the structured envelope: data.stack and data.assigned (name and service.json path of each resource), or errors with a code and suggestions (for example the valid resource names). Set projectPath when the MCP server is not running from the project root.
Inputs: stack (required), resources (required), move, projectPath.
stack_listARead-only
List the project's stacks with their resource counts. Read-only. Use resource_list for the resources themselves. Set services to include each stack's service names, and verbose for its description. Set projectPath when the MCP server is not running from the project root.
Inputs: verbose, services, projectPath.
statusARead-only
Show the live state of the stack: its stacks, resources, their ingress URLs and container ports, the stack-level ports, and Tilt readiness (data.tilt.readiness: ready, pending, failures, enabled; null when no Tilt answers). Read-only. Poll it after up; after a failed up call it first with unhealthy: true to see only the broken services (data.resources and each stack's resources then hold only those; data.unhealthy names them and data.filteredTo says it was trimmed). For the services a project defines whether or not they run use resource_list; for URLs only use network_list; for host checks use doctor. Optionally select the project with projectPath.
Inputs: stack, unhealthy, projectPath.
tool_addADestructive
Add a tool by its everyday name (react, nextjs, fastapi, nodejs, postgresql, mysql, mongodb, rag, embeddings, llm-api) with flisk tool add <tool> --json, which runs the matching flisk resource command. data.status says what happened: resource (created; data.resource is the resource_create result), built-in (docker: nothing to do), manual (angular, tailwind, spring-boot, github-actions, jutro, policycenter: data.steps are steps to show the user; nothing was changed), or an error for a rejected tool (aws, google-cloud, azure, kubernetes): Flisk runs everything locally and never creates cloud resources, so do not work around it. Call up afterwards to start a new resource. Set projectPath when the MCP server is not running from the project root.
Inputs: tool (required), name, stack, dryRun, +1 more.
upA
Start the stack (or part of it) detached from the optional projectPath. The result carries state: ready (every local-process service passed its readiness check), starting (launched, readiness not confirmed: the default after a short wait; poll status, or pass waitForReady), failed (a service exited or gave up; the error carries its own output) or timeout (waitForReady was set and readiness was not reached in waitSeconds; it keeps starting). started: true never means ready. Fails fast on an unknown service, an unsupported host, or a Tilt already running.
Inputs: only, force, stack, dryRun, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Most tools have distinct purposes, and descriptions explicitly cross-reference alternatives such as status vs resource_list vs network_list and doctor vs config_verify. The main overlap is resource_create vs tool_add, plus several project-inspection tools whose boundaries require careful reading.
The set is mostly snake_case with noun_verb names such as resource_create, config_verify, and agent_list, but core lifecycle tools are bare verbs/nouns (up, down, status, logs, doctor), breaking the pattern. Names remain readable but the convention is mixed.
24 tools is heavy for a single MCP server; while the app-builder domain is broad, several read-only diagnostics and list tools could be consolidated. It sits in the borderline 16–25 range.
Lifecycle coverage is strong for init, create, run, restart, verify, up/down, and logs, but there is no resource delete/remove or update tool, and no explicit stack create/delete. These are notable gaps for a full project lifecycle.
Maintenance
Related MCP Connectors
Let your AI agent build, preview and update web apps, download source and publish when you allow it.
Build, host and publish web, web3 (Solana, Base), Android apps and AI agents from a description.
Build and run a business from your AI assistant, with hosting, payments, email and more built in.
Your AI builds, deploys, and runs full-stack apps on a hosted workspace created at first sign-in.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceDeploy full-stack apps from AI. 75+ tools: GitHub/Docker deploy, databases, environments, security, billing.3-
- AlicenseBqualityDmaintenanceEnables non-coders to build software by describing ideas in natural language, orchestrating AI agents and CLI workers via chat without needing a terminal.3023 npm4Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to build and update complete applications, including creating, updating, publishing, previewing, and configuring databases, security, permissions, and server-side integrations.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to build and deploy an app from a GitHub repository to a managed live server and then operate it — logs, captured errors, health checks, managed Postgres, secrets, custom domains, email authentication, and Stripe checkout links. It also exposes safe, read/write-labelled tools so agents can rebuild, start/stop, and inspect projects without ever editing source code.MIT