Config Overview

FlowLayer server config is a single JSONC document.

JSONC keeps local stack files readable, but FlowLayer still validates the file against a strict schema before startup.

Why JSONC

FlowLayer accepts comments and trailing commas, then standardizes the document before decoding it.

That gives you JSONC convenience without loosening the schema:

• comments are allowed
• trailing commas are allowed
• unknown fields are rejected
• invalid field shapes are rejected

If you add a field that the server does not know, config loading fails before any service starts.

Global structure

{
  "session": {
    "bind": "127.0.0.1:6999",
    "token": "dev-token"
  },
  "logs": {
    "dir": ".flowlayer/logs"
  },
  "logView": {
    "maxEntries": 500,
    "all": {
      "maxEntries": 1000
    }
  },
  "services": {
    "db": {
      "cmd": ["postgres", "-D", "./var/db"],
      "port": 5432,
      "ready": {
        "type": "tcp"
      }
    },
    "api": {
      "cmd": ["go", "run", "./cmd/api"],
      "dependsOn": ["db"],
      "port": 3000
    }
  }
}

Top-level fields:

Field	Purpose
session	Enables the server Session API. Use session.bind for the listen address and session.token for Bearer auth.
logs	Disk log projection and in-memory retention. logs.dir enables JSONL files (all.jsonl + per-service); logs.bufferSize (default 5000) caps the per-service in-memory ring buffer — older entries are evicted from RAM (and remain on disk if logs.dir is set).
logView	Optional default limits for get_logs. See Protocol.
services	Service map keyed by service name. See Services, Commands, Startup Waves, and Readiness.

This is server configuration only. The official TUI uses its own client config with session.addr, not session.bind. See Server and TUI Modes.

How the CLI loads config

You can load a file in any of these ways:

flowlayer-server -c ./flowlayer.jsonc
flowlayer-server --config ./flowlayer.jsonc
flowlayer-server ./flowlayer.jsonc

If you do not pass a path, FlowLayer searches the current directory in this order:

1. flowlayer.jsonc
2. flowlayer.json
3. flowlayer.config.jsonc
4. flowlayer.config.json

Using both -c and --config is an error.

Minimal example

{
  "services": {
    "echo": {
      "cmd": ["sh", "-c", "while true; do echo flowlayer-up; sleep 2; done"]
    }
  }
}

Start it with:

flowlayer-server -c ./flowlayer.jsonc

For a first runnable stack, see First Stack. For field-level details, continue with Services.