DEV Community: flisk

The Local Loop Is the Architecture

flisk — Sat, 31 Oct 2026 20:23:44 +0000

We spent a decade teaching systems to cross a network. We are about to spend the next one teaching them not to.

An agent is not a service with a prompt bolted on. It is a runtime that can decide, retry, and call a tool whose effect outlives the call. Put two of those runtimes in different languages — a legal graph in Python, a commercial node in TypeScript — and the interesting design problem is no longer which model you picked. It is which process is allowed to touch the ledger, and how the other processes are prevented from growing their own path to it.

That boundary will not appear in production. By then each team will have a client, a secret, and a story about retries. It has to appear on the laptop, while both agents are still being rewritten every afternoon. The local loop is not a staging copy of the architecture. For this class of system, it is the architecture.

Fragmentation moved

The old fragmentation was operational. Compose files, port maps, a README that lied about the order of docker compose up. Painful, and solvable, because the processes were passive. A worker did not invent a new call while you were looking at a trace.

Agent fragmentation is semantic. The Python node and the TypeScript node can both "check the budget" and mean different things: one reads a view, one posts a reservation, one retries the post because its HTTP client timed out after the database had already committed. They share no type, no credential policy, and no definition of an attempt. Language is the visible difference. Tool ownership is the defect.

A heterogeneous pair makes this obvious.

flowchart LR
  UI[BFF] --> Legal[Legal node\nPython]
  UI --> Commercial[Commercial node\nTypeScript]
  Legal --> ERP[(Ledger)]
  Commercial --> ERP

Two arrows into the ledger is already a distributed system. The model vendors will not design it for you. Neither will a framework that only knows one language. Mastra does not owe LangGraph a session model. LangGraph does not owe your Next.js app a type. The thing they can share is a protocol at the edge of the privileged resource, and a loop that runs all three processes where a human can still watch a retry happen.

A boundary with a name

Call the privileged process a Local Loop Gateway. Agents never receive a connection string. They receive a tool list. The gateway is the only component that can turn a tool call into a query, and the only component that is allowed to remember that a given attempt already happened.

flowchart TB
  UI[BFF\nmints a session]
  subgraph loop [Local loop]
    direction TB
    Legal[Legal node]
    Commercial[Commercial node]
    Bus[Bus]
    GW[Loop gateway\nMCP]
    Legal <-->|events| Bus
    Commercial <-->|events| Bus
    Legal -->|tools| GW
    Commercial -->|tools| GW
  end
  UI --> Legal
  UI --> Commercial
  GW -->|one credential| ERP[(Ledger)]

MCP is the dialect. It is not the control. A schema that says departmentId: string does not stop a second write. What stops the second write is a process that refuses to be a tunnel: closed arguments, named operations, an attempt id stored beside the row.

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "check_department_budget",
      description: "Read the remaining budget for one department.",
      inputSchema: {
        type: "object",
        properties: {
          departmentId: { type: "string", minLength: 1, maxLength: 64 },
        },
        required: ["departmentId"],
        additionalProperties: false,
      },
    },
  ],
}));

The frontier move is not "expose the ERP over MCP." That is how you launder a database into every agent. The move is to publish capabilities, and to make the capability smaller than the fear. check_department_budget can be backed by a view, a procedure, or a fixture. The agent cannot tell, and should not be able to. When the fixture and the procedure return the same shape, you have a boundary. When they do not, you have a demo.

Three properties fall out of putting the tool in a process that is not an agent.

Credentials live in one environment. Adding a third language does not add a third secret.
Argument policy runs before the query is built. Rate limits and sanitization are gateway code, not a paragraph in each agent's system prompt.
The attempt id is a write-side fact. A retry is a cache hit against the ledger, not a second mutation.

None of these are model features. They are what you have left when the model is allowed to call something that matters.

Two channels, not one

Agents that share a ledger still have to negotiate with each other. The failure mode is to make that negotiation another HTTP call, because HTTP is what the laptop already has.

Do not. A tool call and a conversation are different topologies, and collapsing them is how ordering bugs become invisible.

Channel	Carries	Must not carry
MCP, into the gateway	A named operation on a privileged resource	"Ask the other agent"
Bus, between agents	Facts about what an agent decided	A connection string, a retry of a write

The BFF mints x-session-id once per user task. That id is for routing and traces. It is not an idempotency key. A session contains many writes. An attempt contains one. If the commercial node times out on reserve_budget and sends the same attempt id again, the gateway returns the first reservation. If it sends the session id instead, the gateway cannot tell a retry from a second offer, and your ledger grows a twin.

Events stay dull on purpose.

legal.checkpoint.recorded  { session, attempt, departmentId }
commercial.offer.proposed  { session, eventId, terms }

Dull events are how you keep a Python graph and a TypeScript workflow from becoming each other's clients. The moment the commercial node imports a URL for the legal node, you have coupled two hot-reload cycles and called it an architecture.

The loop has to be generated

This pattern dies if the loop is a hand-maintained Compose file. Someone will add a port "just for debugging," point an agent at the database, and the boundary will exist only in the diagram.

The declaration has to be the source, and it has to be local. Flisk is a local control plane for that declaration: one service.json per service, Docker and Tilt generated from it, traffic on *.localhost, no deploy step hiding behind the same command. The legal node, the commercial node, the broker, and the MCP gateway come up as one stack because each file names its dependencies, not because a human remembered an order.

{
  "schemaVersion": 1,
  "appName": "agent-legal",
  "appType": "backend",
  "command": "python agent.py",
  "port": 4001,
  "healthCheckPath": "/health",
  "dependsOn": ["secure-gateway", "event-broker"]
}

flisk doctor
flisk up enterprise-procurement

doctor is part of the architecture. A loop that starts half-up teaches agents to retry against absence, and then you encode that retry as if it were a business rule. Fail before Tilt starts, or you will debug a race that was a missing binary.

Live update is the other half. A change to an evaluation step should appear in the running graph without destroying the session you were tracing. A change to the declaration should not. Routes and dependencies are topology. Topology is regenerated on the next up, not patched in a container that has already forgotten why it is allowed to listen.

There is a second Flisk, at flisk.ai, that manages tags. It is a different system. The one this pattern needs is the CLI that refuses to deploy. That refusal matters. A tool that can both reshape your local boundary and ship it will eventually ship the debug port.

What you are actually testing

A local multi-agent stack is not impressive because five containers started. It is impressive if you can force the failure the production incident will be.

Call a write tool. Kill the client after the gateway has committed, before the agent has seen the response.
Repeat the call with the same attempt id.
Read the ledger. One row, or the pattern is fiction.

Hot reload does not perform that test. Tilt updating a Python file only proves the file was mounted. The test is the duplicate, and the duplicate has to lose.

The same discipline applies to the tool list. If a coding assistant can drive the loop — Flisk can expose the stack over MCP, the reverse direction of an mcp resource — it must not be able to widen a tool because widening was faster than editing the schema. Generated files are not a scratchpad. The assistant proposes a change to service.json. The next up is the merge.

The shift

Monoliths were a packaging decision. Microservices were a team decision. Heterogeneous agents are a permission decision: which runtime may cause an effect, and which runtimes may only request one.

You can postpone that decision until the first double charge. Or you can put a small, closed tool list in a process that holds the only credential, run the disagreeing languages beside it, and watch an attempt id collide with itself before a customer does.

The model will keep changing. The language of each node will keep changing. The boundary should not. Build the loop so that replacing an agent is a service.json and a command, and replacing the ledger is an implementation detail behind a name the agent was never allowed to see.

The Local Loop Gateway

flisk — Sat, 31 Oct 2026 20:22:00 +0000

Agents have stopped being a single chat process. A procurement system might keep its graph in Python because that is where the evaluation library lives, and keep the commercial node in TypeScript because that is where the rest of the product already shares types. Both nodes need the same budget check. Both will retry. Neither should hold the ERP password.

The usual local answer is a hand-written Compose file, a private network, and a growing set of environment variables. It works until the first agent is rewritten in another language, and then the wiring is rewritten with it.

This article describes a local pattern for that situation. I will call it a Local Loop Gateway. Flisk is one way to run the loop: it turns a service.json per service into Docker and Tilt, routes the stack through a local gateway, and does not deploy. The pattern does not depend on Flisk. The tool only removes the part that is usually rewritten by hand.

The problem

Consider two agents and one ledger.

flowchart LR
  UI[Next.js BFF] --> Legal[Legal node\nPython]
  UI --> Commercial[Commercial node\nTypeScript]
  Legal --> ERP[(ERP / ledger)]
  Commercial --> ERP

Each arrow into the ledger is a place where a runtime can grow its own driver, its own secret, and its own idea of what "retry" means. The legal node calls a Python client. The commercial node calls a generated TypeScript client. A third node, added next quarter, copies one of those two and drifts.

Three failures follow, and they are ordinary rather than exotic.

A credential lives in every agent image that needs the ledger.
A retry after a dropped connection writes the ledger twice, because the agent and the ledger do not share a notion of "this attempt."
Changing the budget check means changing every agent, in every language, in the same pull request.

The fragmentation people notice first is language. The fragmentation that costs more is tool ownership: each runtime owns a private path to the same corporate resource.

The structure

Put the tools in a process that is not an agent. Agents talk to that process over MCP. The process is the only thing on the local loop that can reach the ledger.

flowchart TB
  UI[Next.js BFF]
  subgraph loop [Local loop]
    Legal[Legal node\nPython + graph runtime]
    Commercial[Commercial node\nTypeScript]
    Bus[Event broker]
    GW[Gateway proxy\nMCP server]
    Legal <-->|pub/sub| Bus
    Commercial <-->|pub/sub| Bus
    Legal -->|MCP| GW
    Commercial -->|MCP| GW
  end
  UI -->|session id| Legal
  UI -->|session id| Commercial
  GW -->|bounded query| ERP[(Database / ERP)]

MCP is the contract, not the security boundary. The boundary is the proxy: it is the only process with the connection string, the only process allowed to call the ledger, and the only process that can reject a repeated write.

Agents still talk to each other, but not by calling each other's HTTP ports. A negotiation is an event on the broker. A budget check is a tool call. Mixing those two paths is how a "quick RPC" becomes a hidden dependency.

The gateway

The proxy advertises a small tool list. Small is the point. An agent that can run arbitrary SQL is not behind a boundary; it is holding a wider keyboard.

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "check_department_budget",
        description: "Returns the remaining budget for one department. Read only.",
        inputSchema: {
          type: "object",
          properties: {
            departmentId: { type: "string", minLength: 1, maxLength: 64 },
          },
          required: ["departmentId"],
          additionalProperties: false,
        },
      },
    ],
  };
});

Three rules keep this from becoming a pass-through.

Arguments are a closed schema. Unknown fields are rejected in the proxy, before any query is built.
The tool names an operation, not a table. check_department_budget can be implemented as a view, a stored procedure, or a mock. The agent does not get to choose.
Writes carry the caller's attempt id. The proxy stores that id. A second call with the same id returns the first result and does not append another ledger row.

Credentials stay in the proxy's environment. Agent containers receive a URL, not a password. That split is what makes a Python node and a TypeScript node interchangeable from the ledger's point of view: both are MCP clients, and neither can become a database client by editing an env file.

On Flisk, this proxy is an mcp resource in the same stack as the agents. flisk up starts it with the rest of the loop, and its health route is what other services wait on. The scaffold is for *.localhost. It is not an internet-facing ERP facade, and it should not gain one by publishing the port.

One file per service

The loop is several processes with one declaration each. Flisk's unit is a service.json beside the code, not one document that lists every container. From those files it generates the Dockerfile, the Compose entry, the gateway routes, and the Tiltfile. Editing the generated files is how the loop drifts; the next flisk up treats that drift as a mistake.

A backend, in the shape the tool actually expects:

{
  "schemaVersion": 1,
  "appName": "agent-legal",
  "appType": "backend",
  "command": "python agent.py",
  "port": 4001,
  "healthCheckPath": "/health",
  "dependsOn": ["secure-gateway", "event-broker"]
}

The commercial node is the same kind of file, with a different command. The MCP server is a different type — appType: "mcp" — because it is a tool host, not another agent. The broker is a dependency both agents name, so the stack starts in an order a health check can enforce.

flisk doctor
flisk up enterprise-procurement

doctor is worth running first. It fails on a missing runtime or a port clash before Tilt has started half the graph. flisk up then starts the stack and live-updates a container when its code changes. A change to service.json itself is not a live update: routes and dependencies are regenerated on the next up.

What you do not get, and should not pretend you got, is a production orchestrator. Flisk's own description is local-only. The same boundary still has to be rebuilt with your real gateway, your real secret store, and your real network policy. The local loop is a place to discover that the boundary is wrong. It is not the boundary.

Session, bus, and the duplicate write

Two autonomous nodes in a loop will race. The commercial node will counter-offer while the legal node is still writing its checkpoint. A timeout will cause a retry of a call that already committed. None of this is fixed by picking Python or TypeScript.

Keep three identifiers apart.

Identifier	Who mints it	What it means
`x-session-id`	The BFF, once per user task	Sticky routing and trace correlation. Not a write key.
Event id	The publishing agent	Ordering on the bus. Consumers dedupe on it.
Attempt id	The agent, once per tool call	The proxy's idempotency key for a ledger write.

Using the session id as the write key is the mistake that looks tidy in a diagram. A session covers many writes. An attempt covers one. If the commercial node retries reserve_budget after a timeout, the proxy must see the same attempt id and return the reserved row, not reserve again.

Agents publish events. They do not call each other.

legal.checkpoint.recorded   { session, attempt, departmentId }
commercial.offer.proposed   { session, eventId, terms }

A direct HTTP call from the commercial node to the legal node works on a laptop and hides the ordering bug until both are slow. The broker makes the ordering visible, which is the property you want while the system is still small enough to understand.

What this does not solve

The pattern moves credentials and write policy into one process. It does not make that process correct.

A tool that accepts a raw query string has moved the vulnerability into the proxy, which is worse, because every agent can now reach it.
Hot reload does not preserve a careful test. Tilt updating a Python node does not prove the idempotency filter works; a test that posts the same attempt twice does.
Local *.localhost routing is not authentication. A tool with no auth is acceptable on a laptop and unacceptable the moment the port is reachable from another machine.

There is also a product boundary worth stating plainly. "Flisk" is used by more than one company. This article means the local-development CLI at flisk.sh — service.json, Docker, Tilt, no deploy — not the tag-management product at flisk.ai. Mixing the two in a design doc wastes the afternoon the names were supposed to save.

When to use it

Use a Local Loop Gateway when at least two runtimes must share a privileged resource and you are still changing both. The MCP schema is the stable edge. The agent processes are allowed to be boring, replaceable, and written in whatever language already has the library.

Do not use it to avoid an API. If there is one service and one language, a typed client is simpler. MCP pays for itself when the second runtime appears, and when you want the credential, the rate limit, and the duplicate-write rule in one place rather than in every agent.

The local loop is where that rule should fail first. flisk doctor, then flisk up, then a retry of the same attempt id. If the ledger grew a second row, the gateway is still a proxy in name only.

Why the Model Context Protocol (MCP) Is Changing How We Connect AI Frameworks

flisk — Sat, 31 Oct 2026 20:18:48 +0000

When designing multi-agent software, you eventually hit an integration wall: language fragmentation.

Your legal auditing teams prefer Python for its rich scientific tools and ecosystems like LangGraph. Meanwhile, your commercial or user-facing development teams prefer TypeScript for fast, type-safe API platforms like Mastra or Next.js.

If both frameworks need to verify internal ERP limits, read standard database layers, or talk to third-party endpoints, you end up writing identical tool functions twice—once in Python and once in TypeScript. This duplicates your work and doubles your security vulnerabilities.

This is exactly why the Model Context Protocol (MCP) is turning into a fundamental building block for enterprise AI development.

What is MCP?

Developed as an open-source framework, MCP behaves like an open data proxy layer for LLMs. Instead of letting individual agents hook up directly to databases or proprietary external APIs, you implement a single centralized gateway application: the MCP Server.

Your agent networks (regardless of whether they are built on Python, TypeScript, or Go) connect to this proxy server over standard transport channels like Stdio or Server-Sent Events (SSE).

Eliminating Tool Duplication

With an MCP architecture, your tools are decoupled from your agent frameworks entirely. The gateway handles the data exposure securely:

How I Built a Multi-Agent Procurement System with LangGraph, Mastra, and Flisk

flisk — Sat, 31 Oct 2026 20:18:06 +0000

Multi-agent orchestration often sounds easier than it is. When building a system where a Python legal bot needs to debate a TypeScript commercial bot, the infrastructure overhead alone can stall the project. You find yourself wrestling with multiple runtime environments, dockerizing standalone processes, and duplicating tools across separate codebases.

To solve this, I built an enterprise-grade multi-agent procurement system completely locally using Flisk (flisk.sh). Flisk acts as a local runtime gateway, bundling multi-language agents, persistent databases, and event streams into a hot-reloading local stack.

Here is the exact architecture and implementation for a stateful, cross-language procurement network.

The Architecture Setup

The system breaks down into four core decoupled layers:

The BFF & User Interface (Next.js): The control center where contract drafts are uploaded and live AI negotiation loops are monitored on an interactive canvas.
The Legal Agent (Python + LangGraph): A cyclical graph that extracts contract data and checks it against compliance matrices. It includes a Human-in-the-Loop checkpoint gate.
The Commercial Agent (TypeScript + Mastra): A fast TypeScript node that reviews financial lines, balances department limits, and drafts counters.
The Secure Gateway (MCP Server): An abstraction proxy providing bounded local database and mock ERP data access to both agents via the Model Context Protocol.

Setting Up the Stack with Flisk

Instead of crafting manual docker-compose structures, we initialize our resources right out of the box using the Flisk CLI:

# Initialize a local multi-agent stack
mkdir procurement-core && cd procurement-core

# Scaffold the independent runtime environments
flisk resource legal-agent --type agent --stack procurement --yes
flisk resource commercial-agent --type agent --stack procurement --yes
flisk resource secure-gateway-mcp --type mcp --stack procurement --yes

# Spin up the environment 
flisk up procurement

Flisk leverages a local .flisk/procurement/service.json configuration file to unify network paths, set up environment registries, and enable hot-reloading:

{
  "version": "1.0",
  "stack": "procurement",
  "services": {
    "secure-gateway": {
      "image": "node:20-alpine",
      "command": "node dist/index.js",
      "ports": ["3001:3001"]
    },
    "agent-legal": {
      "image": "python:3.11-slim",
      "command": "python agent.py",
      "env": {
        "MCP_GATEWAY_URL": "http://secure-gateway:3001/sse",
        "REDIS_URL": "redis://event-broker:6379"
      }
    },
    "agent-commercial": {
      "image": "node:20-alpine",
      "command": "npx mastra start",
      "env": {
        "MCP_GATEWAY_URL": "http://secure-gateway:3001/sse",
        "REDIS_URL": "redis://event-broker:6379"
      }
    },
    "event-broker": {
      "image": "redis:7-alpine",
      "ports": ["6379:6379"]
    }
  }
}

Streaming Live Negotiations to Next.js

To track AI-to-AI arguments in real time, standard polling doesn't cut it. Both agent nodes stream state updates to our local Redis event broker, which the Next.js BFF hooks into using Server-Sent Events (SSE):

// app/api/negotiation-stream/route.ts
import { NextResponse } from 'next/server';
import { createClient } from 'redis';

export async function GET(request: Request) {
  const redisClient = createClient({ url: process.env.REDIS_URL });
  await redisClient.connect();

  const responseStream = new TransformStream();
  const writer = responseStream.writable.getWriter();
  const encoder = new TextEncoder();

  // Listen directly to the multi-agent network channel
  await redisClient.subscribe('procurement-negotiation-channel', (message) => {
    const eventPayload = `data: ${message}\n\n`;
    writer.write(encoder.encode(eventPayload));
  });

  request.signal.addEventListener('abort', async () => {
    await redisClient.disconnect();
    writer.close();
  });

  return new NextResponse(responseStream.readable, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache, no-transform',
      'Connection': 'keep-alive',
    },
  });
}

Building the Control Canvas

On the frontend, we map incoming data payloads directly to an infinite UI canvas built with @xyflow/react. When an agent is actively working or requests a Human-in-the-Loop check, the node pulses dynamically on the dashboard:

// components/NegotiationCanvas.tsx
import React, { useEffect, useState } from 'react';
import { ReactFlow, Background, Controls, Node, Edge } from '@xyflow/react';
import '@xyflow/react/dist/style.css';

const initialNodes: Node[] = [
  { id: 'user-ui', position: { x: 250, y: 0 }, data: { label: '📥 Ingestion Hub' }, style: { padding: 10, borderRadius: 8 } },
  { id: 'agent-legal', position: { x: 50, y: 150 }, data: { label: '⚖️ Legal Node (Python)' }, style: { padding: 10, borderRadius: 8 } },
  { id: 'agent-commercial', position: { x: 450, y: 150 }, data: { label: '💰 Commercial Node (TS)' }, style: { padding: 10, borderRadius: 8 } },
];

export default function NegotiationCanvas() {
  const [nodes, setNodes] = useState<Node[]>(initialNodes);

  useEffect(() => {
    const eventSource = new EventSource('/api/negotiation-stream');

    eventSource.onmessage = (event) => {
      const data = JSON.parse(event.data);
      setNodes((nds) =>
        nds.map((node) => {
          if (node.id === data.activeAgentId) {
            return {
              ...node,
              style: { 
                ...node.style, 
                backgroundColor: data.status === 'INTERRUPT' ? '#fee2e2' : '#eff6ff',
                borderColor: data.status === 'INTERRUPT' ? '#ef4444' : '#3b82f6',
                boxShadow: '0 0 15px rgba(59, 130, 246, 0.5)'
              },
            };
          }
          return node;
        })
      );
    };

    return () => eventSource.close();
  }, []);

  return (
    <div style={{ width: '100%', height: '500px' }}>
      <ReactFlow nodes={nodes} fitView>
        <Background />
        <Controls />
      </ReactFlow>
    </div>
  );
}

By allowing Flisk to govern the connectivity and lifecycle of our cross-language stacks, we turn what used to be a sprawling infrastructure problem into a smooth, hot-reloading local dev experience.

Mock it or run it? What 44 job roles say about MSW vs running your whole stack

flisk — Wed, 28 Oct 2026 13:26:58 +0000

Every team hits the same wall sooner or later. Your frontend needs an API that isn't ready. Your service needs three other services, a database and a queue. Your test needs the payment provider to fail on purpose.

There are two answers:

Mock it. Pretend the other side exists. Mock Service Worker (MSW) is the best-known way: it catches requests in the browser or in Node and answers with what you tell it to.
Run it. Start the real services on your laptop and talk to them for real: Docker Compose, Tilt, or a tool that wires them up for you (I build one, Flisk; more on that below).

I wanted a less hand-wavy answer than "it depends", so I put both on the same page:

👉 roadmap.flisk.si/roles/?compare=msw,flisk

How the scores work

roadmap.flisk.si is a community-edited map of 372 developer tools. Nobody places a dot by hand. Each tool gets 10 points per checklist item it meets, on two axes:

Easy to use? One command starts it, little setup, see changes fast, clear errors, a screen to look at, working in 10 minutes, Mac/Linux/Windows, no account needed, light and fast, AI can drive it.
Made for big, real systems? Works with containers, handles many services, services talk to each other, real databases and queues, same images as live servers, speaks Kubernetes, works with the cloud, real config and secrets, logs/metrics/traces, works for big teams.

Every check is in a public YAML file. Think a dot is wrong? Open a PR with a source.

The numbers

	Mock Service Worker	Flisk
What it is	API mocking by intercepting requests in browser and Node	Local dev loop for microservices and multi-agent stacks
Easy to use	40/100	80/100
Made for big, real systems	0/100	50/100
Ring	Adopt (use it)	Assess (watch it)
GitHub stars	★ 18.3k	★ 27
Last release	Oct 10, 2026	Oct 24, 2026

The 0 for MSW is not an insult. It is the point. MSW doesn't start containers, doesn't run services, doesn't touch a database. It is a scalpel: it replaces exactly one thing, the network answer, and nothing else. That is why it is fast, light and works with no account and no Docker.

Flisk scores higher on ease of use (one command, little setup, clear errors, a UI, an MCP server) and gets halfway up the other axis (real containers, many services, real databases, services talking to each other). It misses Kubernetes, the cloud and production images, because it is local only by design.

And Flisk is in Assess, not Adopt. Its first release was in October 2026. The ring rule says anything under a year old is "watch it", and the site applies that rule to its own publisher too.

What the roles say

This is the part I found most useful. The site has 44 job roles, each with the tools that job really uses: must have, every day, good to know.

MSW is a must-have for:

Frontend Engineer
Mobile Engineer

…and an every-day tool for:

Full-stack Engineer
QA / Test Automation Engineer
Contract / Integration Test Engineer
Integration Engineer

Flisk shows up in 20 roles, from Backend and Platform Engineer to Forward Deployed Engineer, Tech Lead and Open-source Maintainer. But in every one of them it is only "good to know". Never a must-have.

That is an honest picture of a new tool: broad fit, no one's job depends on it yet. MSW has earned its must-have spots.

So when do you mock, and when do you run?

From the checklists and the roles, my rule of thumb:

Mock it (MSW) when:

You're testing UI states: loading, empty, error, slow, 500, a weird edge case the real API rarely returns.
The API contract is stable, or written down (OpenAPI), and you trust it.
You want tests that run in milliseconds in CI with nothing else installed.
The real backend doesn't exist yet.

Run it when:

The bug lives between services: auth, retries, timeouts, a queue that delivers twice.
You need real data: migrations, indexes, a Postgres that behaves like Postgres.
You're onboarding someone and "clone and it works" matters more than speed.
Your mocks have drifted from reality and nobody noticed. (This is the classic MSW failure: green tests, broken app.)

Usually: both. MSW in unit and component tests, the real stack for integration and for day-to-day development. They are not rivals. They answer different questions, which is exactly what the 0 vs 50 on the "big, real systems" axis is telling you.

Try it on your own stack

Compare any tools: type msw vs flisk, or tilt vs skaffold vs garden, into Ask. It answers from the data, no AI call, and tells you what it can't answer (pricing, benchmarks).
Find your role: rate the tools you know from 0 to 3 in Portfolio. It suggests your best-fit role and draws your skill shape. Your ratings stay in your link; nothing is sent anywhere.
Check the dead stuff: Findings lists tools that are archived or haven't shipped in 18 months, from live GitHub data.

Disclosure

I build Flisk, and Flisk publishes roadmap.flisk.si. That is exactly why the site scores Flisk with the same checklist as everyone else, gives it no special color or size, puts it in Assess, and leaves it off Journeys levels where it doesn't do the job yet.

The first dataset was written in October 2026 with AI-assisted research, so it will have mistakes. If MSW deserves more than 40 for ease of use (I suspect it does: "little setup" and "see changes fast" are arguable), send a PR and the dot moves.

Which camp is your team in: mock everything, run everything, or both?

Bubbles: a new kind of software, where one reply becomes a running stack

flisk — Sun, 25 Oct 2026 13:39:12 +0000

Reply to a post on X with @grok bubbles and a few words about an app. Grok answers with a link. Open the link and you get a running local stack: a web frontend, an API, a database, and a worker, each with its own service.json, a repo built in CI, and, when a runner is free, a live run for up to two hours.

We call this kind of software bubbles. It is not an AI agent, and it is not a code generator. This post explains what it is, how it works, what broke, and what is still rough.

What a "bubble" is

A bubble is a small, complete unit of software that is made from a short description and then checked by ordinary code. Three properties make it a category and not just a demo:

The words pick the parts, nothing else. A fixed menu maps words to parts: postgres adds a database, worker adds a queue, solidity adds a chain node and an indexer. Words that are not on the menu are ignored. Nothing is generated by a model.
Every output is checked before anyone sees it. The plan goes through a validator, then the real Flisk CLI builds the project, and flisk config verify runs in CI. A bubble that does not verify does not get a link.
It is a link, not a session. The result is a web address made of a handle and the words. Share it, bookmark it, open it tomorrow. The same words give the same stack.

Grok is only the trigger. The stack is written by code.

Why not let the model write it?

We tried that first, and it failed the way you would expect. The model confidently invented commands and service types that do not exist. So we removed it from the critical path. Grok asks for a link; a Cloudflare Worker turns the words into a plan; a GitHub Actions run creates the project with the CLI and pushes a branch.

The trade-off is real. A bubble only knows what is on the menu, so an unusual architecture gets a plain default. That is the price of a stack that is the same every time.

How the pipeline works

Worker: reads the handle and words, builds the plan, checks it against rules, and stores the record. Opening a link that does not exist yet starts the build.
CI build: a GitHub Actions run scaffolds the project with flisk, creates one service.json per service, and pushes branch demo/<id> to a public repo.
Live run: a second workflow runs flisk up on a GitHub-hosted Ubuntu runner with Docker and Tilt. Two Cloudflare quick tunnels expose the app and a read-only Tilt UI. Live state is a small live.json on a live/<id> branch, so the Worker reads it from GitHub.
Records: every demo is one JSON file in the same public repo. No separate database.

What broke, honestly

The free storage limit paused saving for hours. Our first design stored records in Cloudflare KV, which has a daily write limit. Once it was hit, new demos could not be saved, and that stopped the whole pipeline. We moved live state to GitHub first, so running demos kept working. Then we moved the records too, so nothing needs KV now.
Runners were not the bottleneck. Every live run started. Each one then failed on the last step, because it tried to save its links to KV.
Next.js did not work on the first try. The generated dev server tried to write .next inside a bind-mounted folder that the container user could not write to. The fix is in review. Next.js support in demos waits for the next flisk release.
The Grok trigger is not reliable yet. Grok sometimes searches instead of answering with a link. We ask it to reply with an exact address, so it is easy to check, but that does not make it certain.

What is still rough

The menu is small. Bubbles cannot describe a custom architecture.
A live run is temporary and shared, so it can be busy.
The first load of a live run can take minutes.
Only one integration (Thor Commerce) is wired by hand. Everything else is a logged request.

Make it yours

Every demo is a plain git branch. The demo page has a "Make it yours" card with the commands to copy the branch into your own repository. Change anything, run it locally with flisk up, and send us what you improved. We will show good changes on the demo page.

Try it: https://demo.flisk.sh. Read how it works in full: https://demo.flisk.sh/how-it-works. The code is in the open: https://github.com/flisk-sh/flisk.

Bubbles are experimental. Tell us what breaks.

What is "@grok bubbles"? A one-line way to get a running local stack from a tweet

flisk — Sun, 25 Oct 2026 01:54:16 +0000

Someone posts "the contract was the easy part". The hard part is everything around it: a frontend, an API, Postgres, background workers, secrets and local routing. Setting that up locally takes an afternoon.

@grok bubbles is our short trigger for that problem. Reply to a post with it, and you get a link to a running local stack built for the person who wrote it.

What happens

Grok replies with a link in the form demo.flisk.sh/<handle>/<what-they-build>.
Opening the link generates the stack from the words in the post: frontend, API, a migrator, workers, a local chain for Solidity.
Each service gets a service.json, produced by code from a fixed menu and checked against Flisk's schema. No model writes the files, so they cannot invent fields.
CI scaffolds a real project with the flisk CLI and checks it with flisk config verify. The result is a branch of a public repo you can clone.
When a slot is free, the stack runs live on a GitHub runner for up to two hours, with a playable app behind a tunnel.

Honest status

The generator, the pages and the live runs work. We have checked each one by hand.

The trigger does not work yet. When we asked Grok "@grok bubbles" on X, it searched for posts and did not use our page. The public llms.txt describes the format, but we have no evidence that Grok reads it while it answers. Treat "@grok bubbles" as a request to be tested, not a feature you can count on.

Until that works, you can use the link directly: demo.flisk.sh/<your-handle>/<words-with-dashes>.

Try it

npm install -g @flisk-sh/flisk
flisk doctor
flisk up

Flisk runs locally on Docker and Tilt. It is a development tool, not a deploy tool.

Bookmark It! STOP Shipping Broken Vibe Code: 10 Checks That Save Your App at 2 AM

flisk — Sat, 24 Oct 2026 22:57:38 +0000

Your demo works. Great. Now try it on a different laptop.

That is where vibe-coded apps die. The agent nailed the happy path, you clicked around, everything looked perfect, and then the first real user typed something weird, a restart wiped the state, or a teammate spent three hours trying to run it. Here are ten checks that stop that from happening.

1. Clone it into an empty folder

Fresh clone. Fresh install. Run it. If it breaks, your app depends on something living only on your machine. Find it and kill it.

2. Use the CI install, not your shortcut

Run the same clean install command your pipeline runs. A lockfile that is out of step with the manifest passes on your laptop and fails in CI, every single time.

3. Hunt the secrets

Search the diff for keys, tokens, and connection strings. Agents love copying example values into real code. Move every secret to the environment and make sure the env file is git-ignored.

4. Put a timeout on everything

An outbound call with no timeout will wait forever when the other side stalls. Give every call a limit, and check what the user sees when it fails.

5. Break the input on purpose

Send an empty field, text where a number belongs, and a value far outside the expected range. The app should answer with a message someone can act on, not a crash or a blank screen.

6. Start the database first

If the API boots before Postgres accepts connections, the first request fails in a confusing way. Declare the dependency and wait for readiness. In Flisk, migrations run in their own migrator resource (appType: migrator), ordered after Postgres and before the API. flisk doctor flags a service that runs a migration from its own start script.

7. Migrate once, not on every restart

A migration in your app's startup path runs on every restart, and two instances can run it at the same time. Move it into a separate step that runs once, before anything else starts.

8. Make the health check honest

A route that always returns 200 tells you the process is alive, not that the service works. Check what the service actually needs, and keep the check cheap enough to run constantly.

9. Never hand-edit generated files

If a tool writes your Dockerfile or routing config, edit the source, not the output. Hand edits get wiped on the next generation, quietly. Flisk checks its generated files against saved snapshots before flisk up starts, so a hand edit blocks startup and names the file.

10. Break it and read the log

Stop the database. Throw an error in one route. Delete an environment variable. Every time, the log should say what failed and where. If it doesn't, fix that before anyone else sees the app.

The bottom line

Run all ten once. Most vibe-coded projects pass the first three and fall apart on the last few. The fixes are small. Skipping them costs you a weekend and a very confused teammate.

Your demo is not the product. Your demo that survives a clean clone is.

Two Good First Issues in Flisk You Can Finish This Weekend

flisk — Sat, 24 Oct 2026 11:16:48 +0000

Your first contribution to an open-source project should be small, checkable, and useful. Flisk has two open issues that fit that description. Both are documentation work, both are labelled as good first issues, and both have a way to prove the change is right.

Issue 1: document the /turn request body

The agent resource in Flisk exposes a /turn route. The docs show how to call it with an x-session-id header, but they do not show the JSON body. A newcomer cannot tell which field carries the message.

The task is to add the exact request body and one sample response, checked against a running agent. Scaffold one with flisk resource bot --type agent --stack shop --yes, start it with flisk up shop, send a real request, and write down what it accepted.

Read the issue: #2031.

Issue 2: verify the @ref syntax in the worker recipe

The worker recipe passes connection strings with @ref(postgres.DATABASE_URL) and similar values. The recipe does not say whether that form is supported in every case, or what the worker receives once it is resolved.

The task is to find where the reference is resolved in the source, then either confirm the syntax with a link to that code, or correct the recipe. A container check shows the value the worker sees.

Read the issue: #2032.

How to contribute

Sign off every commit with git commit -s. The repository's Developer Certificate of Origin check fails without it. Keep one issue to one pull request, and read the contributing guide first.

If you finish either task, say what you ran and what you saw. That note is the evidence a maintainer needs to merge quickly.

How Flisk Routes Agent Traffic: A Sequence Diagram of One Turn

flisk — Sat, 24 Oct 2026 11:07:34 +0000

The earlier articles covered the agent, the MCP resource, and the control plane. This one follows a single turn: one request from a client to an agent, through the gateway, the checkpoint store, and back.

The sequence follows the Flisk agent docs. The model call is a placeholder, since your runTurn decides what it looks like.

The sequence

sequenceDiagram
    autonumber
    actor User as Client
    participant GW as Traefik gateway
    participant Agent as Agent service
    participant Store as Checkpoint volume
    participant Model as Model provider (your code)

    User->>GW: POST /api/bot/turn with x-session-id
    GW->>Agent: route by session header
    Agent->>Store: load checkpoint for the session
    alt no checkpoint yet
        Store-->>Agent: empty state
    else checkpoint exists
        Store-->>Agent: prior messages
    end
    Agent->>Agent: append the user's input
    Agent->>Model: runTurn(checkpoint, input)
    Model-->>Agent: reply and updated state
    Agent->>Store: commit the checkpoint atomically
    Store-->>Agent: committed
    Agent-->>GW: reply
    GW-->>User: reply

    Note over Agent,Store: On SIGTERM an in-flight turn finishes and checkpoints first
    Note over Store: The named volume survives flisk down

Where state lives

The session state sits in a checkpoint store, a file per session on a named Docker volume. The turn reads it first and writes it last. The write is atomic, so a crash partway through does not leave a half-saved conversation.

Because the volume outlives flisk down, a restarted agent loads the same state the next turn needs. The docs also say an explicit volume removal is the only way to lose it, which is a deliberate safeguard.

What routing does

The gateway uses the x-session-id header to choose the session. Two conversations never share a checkpoint, even when they hit the same agent service. The header is also the one thing a client must get right: a missing or changed session ID starts a new conversation.

What a restart does

If the agent restarts between turns, the next turn loads the checkpoint and carries on. If it restarts during a turn, the drain on SIGTERM lets the in-flight turn finish and checkpoint first. The docs say live-update reloads use the same path.

A crash rather than a clean stop skips the drain. The atomic commit then protects the last saved state, and the turn in progress is lost. Plan for that in your client: retry the request with the same session ID, and check whether the turn was saved.

What to check before you trust it

Send two turns with one session ID, restart the stack, and send a third turn. The third reply should reflect the first two. Then send a turn with a new session ID and confirm it starts fresh. Those two checks cover the parts that break quietly.

Summary

One turn goes through the gateway, which routes by session. The agent loads the checkpoint, calls your model code, commits the new state atomically, and replies. The state survives a restart because it lives on a volume, and a clean stop drains the turn in progress. Test the two-turn, restart, third-turn path before you depend on it.

Running a Python or LangGraph Agent as a Flisk Worker, With Dependencies Declared

flisk — Sat, 24 Oct 2026 11:07:17 +0000

Not every agent answers HTTP requests. Some work through a queue: they pick up a task, call a model, write a result, and wait for the next one. Flisk's worker resource type fits that shape. The docs describe a Python or LangGraph agent running as a worker, with Postgres and NATS declared as dependencies.

Scaffold the worker

flisk resource research-agent --type worker --stack shop --yes

Then declare what the worker needs in its service.json:

{
  "name": "research-agent",
  "appType": "worker",
  "stack": "shop",
  "dependsOn": ["postgres", "nats"],
  "env": {
    "DATABASE_URL": "@ref(postgres.DATABASE_URL)",
    "NATS_URL": "@ref(nats.NATS_URL)"
  }
}

The dependsOn list sets the start order. The @ref(...) values pull connection strings from the services you named, so the worker does not hard-code them.

What the order guarantees

The docs say the worker boots only after Postgres and NATS pass their readiness gates. That matters for an agent. A worker that starts before its queue is up will fail on its first poll, and the failure looks like a bug in the agent rather than a startup race.

They also say the worker reconnects smoothly during a hot reload. Check that behaviour in your own setup, since reconnect logic lives in your code as much as in the stack.

What the worker should do

A worker agent should be idempotent. A task that runs twice should not send two emails or write two rows. Use the task ID as a key, and write the result before you mark the task done.

Log each task with its ID. When a task fails, you need to find the run that failed, not scroll through a stream.

Set a retry limit. A worker that retries a failing model call forever burns cost. After the limit, move the task to a failed state with the error attached.

Check the start order

Before you rely on it, run the dry run and read the plan:

flisk up shop --dry-run

The plan should show Postgres and NATS before the worker. If it does not, the dependsOn list is wrong, and the worker will start too early.

What a worker is not

A worker is not a session server. There is no x-session-id routing, because a queue does not carry conversations. If your agent needs a conversation that survives a restart, the agent resource is the closer fit, as the first article in this series covers.

Summary

A background agent fits the worker resource. Declare its database and broker in dependsOn, pass their URLs with @ref, make the task handling idempotent, cap the retries, and check the start order in the dry run before you start.

Flisk as a Control Plane: Let Your Coding Assistant Run the Whole Local Stack

flisk — Sat, 24 Oct 2026 11:06:51 +0000

The mcp resource puts an agent's tools inside your stack. The flisk mcp command does the reverse: it lets an assistant control the stack. Run it over stdio, and a coding assistant can check the machine, start services, read their status, and read bounded logs.

Connect it

The Flisk docs give the same entry for the MCP clients they name, Claude Code, Cursor, and Codex:

{
  "mcpServers": {
    "flisk": {
      "command": "flisk",
      "args": ["mcp"]
    }
  }
}

The server runs from the project folder, so it finds the project's configuration. Set the working directory in your client, or the assistant will be looking in the wrong place.

What it can do

The docs list four jobs:

doctor diagnoses the container runtime and port conflicts.
up and down start and stop services.
status returns structured health, so the assistant can see whether APIs and databases are ready.
logs returns a bounded window of output for debugging.

The bounded logs matter. A full log dump fills an assistant's context and hides the one line that matters. A tail with a limit keeps the conversation focused.

A loop that works

Give the assistant a procedure, not a goal:

Run doctor. Stop and report if the runtime is missing.
Run up for the services the task needs.
Poll status until the services are ready, or until a failure appears.
On failure, read the logs for the failing service only.
Report what you found, with the status output as evidence.

up returns before the stack is ready, so the poll is what gives the assistant a finish line. Without it, the assistant may report success after the start command returns, which is a common failure.

What to keep out of its reach

A control plane can start and stop everything, so decide the limits before you connect it. Stopping a local stack is low-risk. Deleting volumes, which holds your data, is not, and the docs treat the volume as something you remove explicitly. Keep those steps with a person.

Generated files are also off limits. The contributor guidance says not to edit generated output, and an assistant that changes it will be overwritten on the next generation. Put that rule in the project instructions the assistant reads.

Check it by hand first

Before you hand the stack to an assistant, run the same loop yourself: flisk doctor, flisk up, flisk status --json, and flisk down. If the loop fails for you, it will fail for the assistant, and the error will be harder to read inside its output.

Summary

flisk mcp gives an assistant a structured way to run the local stack: check, start, poll, read bounded logs, and stop. Give it a procedure with a finish line, keep destructive steps with a person, and test the loop yourself before you connect the assistant.