Skip to main content

Server and TUI Modes

FlowLayer is intentionally split into two modes backed by two binaries.

Server mode (flowlayer-server)​

The server is the runtime source of truth.

Responsibilities:

  • load and validate config
  • orchestrate process lifecycle
  • hold runtime service state
  • store in-memory logs and optional disk projection
  • expose session API when enabled

Session API activation:

  • enabled via -s or session.bind
  • disabled when no effective bind is resolved

That means a server can run orchestration with no API surface at all.

TUI mode (flowlayer-client-tui)​

The TUI is an external client.

Responsibilities:

  • observe runtime state (snapshot, service_status, log)
  • send runtime commands over WebSocket
  • maintain local UI state only

The TUI does not own orchestration truth.

Address semantics: server vs client​

Server and TUI use different config fields:

  • session.bind (server): where the server listens
  • session.addr (TUI): where the TUI connects

Do not treat them as a shared field.

Server config example​

{
	"session": {
		"bind": "127.0.0.1:6999",
		"token": "dev-token"
	},
	"services": {
		"api": {
			"cmd": "go run ./cmd/api"
		}
	}
}

TUI config example​

{
	"session": {
		"addr": "127.0.0.1:6999",
		"token": "dev-token"
	}
}

Typical development workflow​

  1. Start server (flowlayer-server) with your stack config.
  2. Enable session API only when you need remote client access.
  3. Connect TUI (flowlayer-client-tui) to observe and operate the running session.

For endpoint and protocol details, continue to HTTP API Overview and Protocol Overview.