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 & TUI Modes.