Server

// Server Runtimev1.1.1

Single runtime authority

flowlayer-server is the only orchestration authority in a FlowLayer session. It owns config resolution, dependency planning, lifecycle transitions, runtime truth, and Session API access.

Overview

flowlayer-server is the runtime engine that turns one config file into a live, controllable session. It validates config, computes startup order, launches services, exposes authenticated endpoints, and emits canonical state and logs to every client.

# Typical boot
flowlayer-server -c flowlayer.jsonc -s 127.0.0.1:6999

# Typical client attachment (official TUI)
flowlayer-client-tui -addr 127.0.0.1:6999 -token <token>
flowlayer-client-tui -config flowlayer.jsonc

Deterministic startup plan

For a given valid config, dependency validation and wave planning are deterministic. The plan is computed once at boot and then executed.

What the Server Owns

Domain	Server ownership	Not delegated to clients
Config intake	Parse JSONC, validate schema, resolve config path	Clients do not reinterpret config policy
Startup planning	Build DAG, compute waves, enforce dependency gates	Clients cannot reorder service startup
Session surface	Start and guard /health and /ws	Clients do not publish session endpoints
Runtime truth	Canonical service states, events, command outcomes, logs	Clients only render or request
Shutdown policy	Reverse-order teardown, stopCmd or signal path	Clients do not signal processes directly

This ownership model is why multiple clients can connect without creating divergent runtime behavior.

flowlayer-server

Server

Orchestration engine. Owns service state, lifecycle, logs, and Session API. Single runtime authority.

flowlayer-client-tui

TUI Client

Official terminal client. Connects over WebSocket. Observer and control surface. Separate binary.

CLI Usage

flowlayer-server [-c <path>] [--config <path>] [<path>] [-s <bind>] [-token <value>] [--no-color] [-h|--help] [--version]

Behavior summary:

• Running with no explicit config path triggers config auto-discovery in the current directory.
• --help and -h print help and exit 0.
• --version prints version and exits.
• Invalid CLI/config combinations print Error: <message>, then help, then exit 2.

Flags Reference

Flag	Purpose	Notes
-c <path>	Primary explicit config path	Highest config-path precedence
--config <path>	Alternate explicit config path	Cannot be combined with -c
<path> (positional)	Config path by position	More than one positional arg is invalid
-s <bind>	Enable Session API and set bind	Overrides session.bind
-token <value>	Session bearer token override	Overrides session.token
--no-color	Disable ANSI color output	Equivalent effect to non-empty NO_COLOR
-h, --help	Print help and exit	Same output as bare help mode
--version	Print binary version and exit	No config required

Accepted -s forms:

• host:port
• :port
• bare port (interpreted as loopback bind)

Examples:

flowlayer-server -s 6999 -c ./services/flowlayer.jsonc
flowlayer-server -s :6999 -c ./services/flowlayer.jsonc
flowlayer-server -s 192.168.1.10:6999 -c ./services/flowlayer.jsonc

Config Path Resolution

Resolution order (highest to lowest):

1. -c <path>
2. --config <path>
3. positional <path>
4. auto-discovery in current directory

Auto-discovery order:

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

Invalid combinations:

• -c with --config in the same invocation
• more than one positional config path
• no discoverable config file and no explicit path

Failure mode: exit code 2 with help text.

Configuration Precedence

Server behavior combines CLI and config values with strict precedence.

Concern	Precedence chain
Config file path	-c -> --config -> positional -> auto-discovery
Session bind	-s -> session.bind -> Session API disabled
Session token	-token -> session.token -> generated token (if Session API enabled)
Color output	--no-color or NO_COLOR -> no ANSI color

Example session block:

{
   "session": {
      "bind": "127.0.0.1:6999",
      "token": "change-me"
   }
}

See Configuration for full schema.

Session Bind / Address Model

The Session API listener is opt-in.

• If neither -s nor session.bind is set, no Session API is started.
• If enabled, listener startup happens during boot, before service wave execution.
• Bind failure is fatal: the server exits rather than running in partial mode.

Operational guidance:

• Prefer loopback binds (127.0.0.1:PORT) for local development.
• Use :PORT or non-loopback interfaces only when intentionally exposing the API.

Authentication Token Model

All Session API requests require bearer authentication.

Token source priority:

1. -token
2. session.token
3. auto-generated token (fl_<uuid> pattern)

boot token output

$ flowlayer-server -c flowlayer.jsonc -s 127.0.0.1:6999[flowlayer] boot: session token: fl_d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8[flowlayer] boot: session API: 127.0.0.1:6999 (/ws, /health)

Request header:

Authorization: Bearer <token>

Auth outcomes:

Condition	Result
Missing Authorization header	401 Unauthorized
Header present but token mismatch	403 Forbidden
Valid bearer token	Request proceeds

The generated token is a session credential for local/dev operation, not a full production identity system.

Session API

The runtime exposes two authenticated endpoints.

/health

• Method: GET
• Auth: bearer token required
• Purpose: liveness check of running session server
• Response while live:

{"ok": true}

/ws

• Method: GET (WebSocket upgrade)
• Auth: bearer token required
• Purpose: protocol transport for state, logs, and control commands

Handshake order on successful connect:

1. hello
2. snapshot
3. incremental runtime events and command traffic

Protocol details: Protocol.

Runtime State Model

The server maintains canonical runtime state for all connected clients.

Runtime output	Meaning for clients
snapshot	Full baseline state for newly connected client
status/lifecycle events	Incremental changes after snapshot
command ack and result	Request acceptance and completion outcome
log events	Live merged stdout/stderr stream (best effort)

Service lifecycle interpretation is server-owned. Clients do not synthesize independent state from local assumptions.

Logs Aggregation

Server log behavior in the session model:

• Aggregates logs from tracked services into one timeline.
• Emits live log events on the WebSocket stream.
• Supports replay via get_logs for reconnect and catch-up flows.
• Can persist canonical logs when server-side log persistence is configured.

Practical implications:

Situation	Server behavior
Slow or disconnected client	Client may miss live events; replay fills gaps
Reconnect with high-water sequence	Replay can request after_seq continuity
Multiple clients connected	All observe the same canonical log stream model

Process Orchestration

At boot, orchestration follows a strict sequence:

1. Validate config and dependency graph.
2. Compute DAG and startup waves.
3. Start Session API listener (if configured).
4. Launch wave 0 services concurrently.
5. Advance to next wave only after current wave reaches terminal startup outcomes.

boot.output

$ flowlayer-server -c flowlayer.jsonc -s 127.0.0.1:6999[flowlayer] boot: validating config and graph…[flowlayer] boot: session API: 127.0.0.1:6999 (/ws, /health)[flowlayer] boot: session token: fl_d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8[flowlayer] boot: DAG computed — 3 nodes, 2 waves[flowlayer] boot: wave 0 │ billing → starting[flowlayer] boot: wave 0 │ ping → starting[flowlayer] boot: wave 0 │ billing → ready (http :3002/healthz)[flowlayer] boot: wave 0 │ ping → ready (tcp :8088)[flowlayer] boot: wave 1 │ users → starting[flowlayer] boot: wave 1 │ users → ready (http :3003/healthz)STARTUP COMPLETE — runtime active

Control commands accepted through protocol path include:

• start_service
• stop_service
• restart_service
• start_all
• stop_all

Clients request these actions; server policy validates and executes them.

Readiness Lifecycle

Readiness is part of startup gating, not just a UI hint.

Stage	Description
Planned	Service included in validated DAG and wave
Starting	Process launch initiated by wave execution
Running or ready	Terminal startup success condition for wave progression
Failed startup	Service fails before readiness, affecting dependents
Blocked	Downstream service waits for upstream readiness/success

Illustrative flow:

config -> DAG/waves -> start wave N -> wait for startup outcomes -> unlock wave N+1

Shutdown Behaviour

Shutdown begins when server receives SIGINT or SIGTERM.

Sequence:

1. Stop Session HTTP server first.
2. Apply short grace period for in-flight HTTP requests (2 seconds).
3. Tear down services in reverse dependency order.
4. For each service, use stopCmd if defined; otherwise signal process group.
5. Wait for graceful process exit window.
6. Force remaining processes with SIGKILL.

01.Session HTTP server stops. 2-second grace for in-flight requests.

02.Services torn down in reverse dependency order.

03.Per-service: if stopCmd is defined, it runs instead of SIGTERM.

04.If no stopCmd: SIGTERM to the process group. 8-second wait for I/O flushing.

05.Any remaining processes receive SIGKILL.

Timeouts from source behavior:

• HTTP grace: 2 seconds
• signal-based process wait: 8 seconds before forced kill path

stopCmd vs signal flow

Aspect	stopCmd path	Signal path
Trigger	Service defines stopCmd	No stopCmd defined
Mechanism	Execute explicit stop command	Send SIGTERM to tracked process group
Environment	Same effective env as service cmd, including service env overrides	N/A (signal delivery)
Graceful intent	Runtime-specific shutdown command (useful for wrappers)	Generic process termination
Fallback	If process remains, eventual force-kill path still applies	SIGKILL after grace window

Use stopCmd for runtimes that need explicit shutdown semantics.

Process Isolation

The server uses a track-only registry model:

• It manages only processes it spawned and registered.
• External/untracked processes are never signaled.
• This prevents accidental interference with unrelated machine workloads.

TRACKED

Signals and lifecycle management apply only to processes spawned and registered by the server. External processes are never touched.

EXTERNAL

Unregistered processes remain untouched and unaware. This prevents accidental interference with unrelated machine workloads.

Execution model constraints:

• Commands are executed directly.
• Shell operators are not interpreted unless a shell is explicitly invoked.
• For shell semantics, wrap explicitly (for example sh -c "...") in config command arrays.

No implicit shell parsing

&&, pipes, and redirects are shell features, not command-array features. Use explicit shell invocation only when you need shell behavior.

Security Notes

Security posture in this runtime model:

• Every request to /health and /ws is authenticated.
• Token control is session-scoped, not user-account-scoped.
• Bind address selection materially changes exposure.
• Runtime action authority remains centralized in the server.

Operational baseline:

1. Keep binds on loopback unless remote access is intentional.
2. Treat session token as sensitive for the lifetime of the session.
3. Rotate by restarting session when access scope changes.

Common Operating Patterns

Pattern A: local deterministic startup and attach

flowlayer-server -c ./services/flowlayer.jsonc -s 127.0.0.1:6999
flowlayer-client-tui -addr 127.0.0.1:6999 -token <token>

Use when validating startup order and readiness gating quickly.

Pattern B: config-driven session endpoint

flowlayer-server -c ./services/flowlayer.jsonc
flowlayer-client-tui -config ./services/flowlayer.jsonc

Use when team workflow already stores session values in config.

Pattern C: investigate failed startup before restart loops

1. Review failure logs in client.
2. Confirm dependency readiness conditions.
3. Apply targeted restart_service only after cause is understood.

This avoids hiding root cause with blind restart cycles.

Participation and Issue Flow

Collaboration paths aligned with the server page content:

• Bug reports and feature requests go through project issue tracking.
• Protocol and configuration surfaces are documented publicly.
• Alternative clients remain possible through the public protocol contract.

Practical references:

• Issues: https://github.com/FlowLayer/flowlayer/issues
• Protocol documentation: Protocol
• Config documentation: Configuration

Download binariesServer sourceGitHub IssuesProtocol specClient / TUI

Known Limits

• Not a production supervisor for long-lived remote fleets.
• No automatic restart policy for crashed services by default.
• No implicit shell parsing for service command arrays.
• No control over external processes outside tracked registry.
• Session token model is intentionally lightweight for development sessions.

Related Pages

• Configuration
• Protocol
• Client / TUI
• Troubleshooting
• Reference
• Marketing overview: /server/