Skip to main content

Run a Multi-Service Stack

Use this recipe when you want one command to boot a realistic local stack: database, API, worker, and frontend.

This page focuses on a practical baseline. For field-by-field details, see Services, Commands, Waves, and Readiness.

Example config​

{
	"session": {
		"bind": "127.0.0.1:6999",
		"token": "dev-token"
	},
	"services": {
		"postgres": {
			"cmd": ["postgres", "-D", "./var/postgres"],
			"port": 5432,
			"ready": {
				"type": "tcp"
			}
		},
		"api": {
			"cmd": ["pnpm", "--dir", "services/api", "dev"],
			"dependsOn": ["postgres"],
			"port": 3000,
			"ready": {
				"type": "http",
				"url": "http://127.0.0.1:3000/health"
			}
		},
		"worker": {
			"cmd": ["pnpm", "--dir", "services/worker", "dev"],
			"dependsOn": ["postgres"]
		},
		"frontend": {
			"cmd": ["pnpm", "--dir", "web", "dev"],
			"dependsOn": ["api"],
			"port": 5173,
			"ready": {
				"type": "tcp"
			}
		}
	}
}

What this gives you:

  • dependsOn gates startup order through graph-derived waves
  • session.bind enables Session API for TUI or custom clients
  • postgres and frontend use TCP readiness
  • api uses HTTP readiness on /health

Launch the full stack​

flowlayer-server -c ./flowlayer.jsonc

Expected plan shape:

  • wave 0: postgres
  • wave 1: api and worker
  • wave 2: frontend

Then connect the official TUI:

flowlayer-client-tui -addr 127.0.0.1:6999 -token dev-token

Server and TUI config files are separate:

  • server config uses session.bind
  • TUI config uses session.addr
  • do not pass the server flowlayer.jsonc to the TUI unless that file is explicitly written as a TUI config

Read logs​

Two common paths:

  1. Open logs in the TUI while services are running.
  2. Pull logs through WebSocket get_logs for scripted checks. See Logs.

For example, filtering one service through the protocol:

{
	"type": "command",
	"id": "logs-api-1",
	"name": "get_logs",
	"payload": {
		"service": "api",
		"limit": 200
	}
}

Common operations​

  • Restart one service after a code change: restart_service with payload.service.
  • Pause one service without stopping everything: stop_service.
  • Resume it later: start_service.
  • Stop the full stack: stop_all, or press Ctrl+C in the server terminal.

Available runtime commands are listed in Actions.

Troubleshooting quick checks​

  • api blocked: check whether postgres reached TCP readiness.
  • frontend blocked: check whether api became ready on /health.
  • TUI cannot connect: verify session.bind and token value.

If you need stricter orchestration behavior, continue with Use Startup Waves and Add Readiness Checks.