Skip to main content

First Stack

This walkthrough starts a minimal FlowLayer server stack, then shows how to connect the official TUI with explicit session parameters.

1. Create a minimal server config​

Create a flowlayer.jsonc in your working directory:

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

This is intentionally server-only. No client configuration is required to run the stack.

2. Start the server​

The commands below use the downloadable server binary name flowlayer-server.

flowlayer-server -c ./flowlayer.jsonc

Expected behavior:

  • boot phase validates config and computes startup plan
  • start phase launches services
  • runtime phase waits for termination signal

3. Understand API mode vs non-API mode​

Without a session bind, the Session API is not exposed.

To enable the Session API explicitly:

flowlayer-server -c ./flowlayer.jsonc -s 127.0.0.1:6999 -token dev-token

Activation sources are:

  • CLI flag -s
  • or server config field session.bind

If neither is set, there is no session HTTP API.

4. Connect the TUI explicitly​

When session API is active, connect the official TUI with explicit address and token:

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

If you do not pass -token and the server auto-generates one, use the token printed by server boot logs.

5. Quick checks​

Health endpoint (when session API is enabled):

curl -H "Authorization: Bearer dev-token" http://127.0.0.1:6999/health

Expected response:

{"ok": true}

Troubleshooting​

  • If flowlayer-client-tui cannot connect, confirm -s bind and token values first.
  • If /health returns 401 or 403, check the Authorization: Bearer <token> header.

For role boundaries and configuration semantics, see Server and TUI Modes.