Flisk

Flisk: your whole app, running on your computer with one command

[What is Flisk?](#what-is-flisk) · [Key features](#key-features) · [Quick start](#quick-start) · [Commands](#commands) · [Configuration](#configuration) · [With your AI agent](#use-flisk-with-your-ai-agent) · [FAQ](#faq) · [Docs](#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 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-shop

flisk project --yes flisk resource orders-api --type backend --stack shop --yes flisk resource shop-web --type frontend --stack shop --yes flisk 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).

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?

Three quick questions; click the answer closest to your team. Not technical? Pick "not sure" where you need to. You get a score and a plain-English why.

1. What is the app written in?

1. How do developers start the app on their laptop today? <img src="docs/assets/fit/setup-container-ui.0b9bc816.svg" alt="A Docker app" w