Reference

// Quick Operator Referencelookup

Compact lookup for config keys, CLI flags, common commands, and protocol envelopes — the page to keep open while you run, observe, and document a local session.

Sibling references

For HTTP & WebSocket endpoint contracts, see API Reference. For the full WebSocket message specification, see Protocol. This page is the operator-facing index that points to both.

Core Runtime Items

Item	Role	Notes
flowlayer-server	Orchestration engine	Source of truth for planning, lifecycle, state, and logs.
flowlayer-client-tui	Official client	Connects to Session API to observe and control runtime.
flowlayer.jsonc	Runtime input	Strict JSONC; unknown fields are rejected.
Session token	API auth credential	Required for /health and /ws access.

Config Discovery and Overrides

Discovery order (when no path is passed)

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

CLI override rules

• Config path: -c or --config override discovery.
• Session bind: -s overrides session.bind.
• Session token: -token overrides session.token.

Common Config Keys

Key	Type	Purpose
session.bind	string	Address used by server Session API listener.
session.addr	string	Address used by client config mode.
session.token	string	Bearer token for authenticated API access.
services	object map	Service definitions keyed by service name.
services.<name>.cmd	string or string[]	Process command (array form recommended for exact argv).
services.<name>.dependsOn	string[]	Dependency edges used by DAG planning.
services.<name>.ready	object	Readiness gate for downstream unlock.
services.<name>.kind	daemon or oneshot	Lifecycle behavior profile.
logView.*	object	Default limits for log retrieval responses.

Service fields

Field	Type	What it controls	Notes
cmd	string or string[]	Process execution	String form is split on whitespace; array form is safest for exact argv.
port	integer	Default service port	Used by TCP readiness when ready.port is omitted.
env	object	Service-local environment	Merged with parent environment for both cmd and stopCmd.
ready	object	Readiness gate	Blocks downstream dependsOn edges until success.
dependsOn	string[]	Dependency edges	Produces deterministic startup waves from the DAG.
kind	string	Lifecycle shape	daemon for long-running, oneshot for setup jobs.
stopCmd	string or string[]	Custom teardown	Replaces default signal-based stop behavior.

cmd: string vs array

{
  "services": {
    "frontend": {
      "cmd": "pnpm --dir ./frontend dev"
    },
    "backend": {
      "cmd": ["sh", "-c", "cd backend && pnpm start"]
    }
  }
}

Use string form for simple commands. Use array form when arguments contain spaces or when you need an explicit shell invocation.

dependsOn, kind, stopCmd

{
  "services": {
    "postgres": {
      "cmd": ["docker", "compose", "up", "postgres"],
      "stopCmd": ["docker", "compose", "down", "postgres"],
      "ready": { "type": "tcp", "port": 5432 }
    },
    "migrate": {
      "cmd": ["pnpm", "--dir", "./services/users", "run", "db:migrate"],
      "kind": "oneshot",
      "dependsOn": ["postgres"]
    }
  }
}

Readiness probes

Key	Status in v2	Meaning	Notes
tcp	Supported	Wait for a TCP handshake	Uses ready.port or falls back to service port.
http	Supported	Poll a URL until it returns success	Use for app-level health endpoints.
interval	Fixed	Probe cadence	Current docs expose a fixed 200ms polling interval.
timeout	Not exposed	No per-probe timeout field documented	Treat slow start as repeated polling until success or process exit.
maxAttempts	Not exposed	No retry cap field documented	Current behavior retries until success or process death.

{
  "services": {
    "api": {
      "cmd": ["node", "dist/server.js"],
      "port": 3001,
      "ready": {
        "type": "http",
        "url": "http://127.0.0.1:3001/health"
      }
    },
    "redis": {
      "cmd": ["docker", "compose", "up", "redis"],
      "port": 6379,
      "ready": { "type": "tcp", "port": 6379 }
    }
  }
}

CLI override rules

Concern	Default behavior	CLI override	Effective rule
Config path	Auto-discovery in current directory	-c or --config	Explicit flag wins over discovery.
Bind addr	session.bind from config	-s	CLI bind wins over config bind.
Token precedence	session.token from config or generated token	-token	-token wins, then config, then auto-generated token.

flowlayer-server -c ./services/flowlayer.jsonc -s 127.0.0.1:7010 -token dev-token
flowlayer-client-tui -config ./services/flowlayer.jsonc

Logging / logView

Key	Scope	Used for
logView.maxEntries	Global override	Explicit override when clients request logs without a limit and no more specific override applies.
logView.all.maxEntries	All-services view	Override for aggregated log queries.
services.<name>.logView.maxEntries	Per service	Override for one service’s default retrieval cap.
logs.bufferSize	Runtime ring config	Default limit when no explicit limit and no applicable logView override are present (default 5000).
effective_limit	Server response value	The actual limit clients should respect in their local buffer.

{
  "logView": {
    "maxEntries": 500,
    "all": { "maxEntries": 800 }
  },
  "services": {
    "billing": {
      "cmd": ["pnpm", "--dir", "./services/billing", "run", "start:dev"],
      "logView": { "maxEntries": 200 }
    }
  }
}

The server stays in charge of retention decisions. Clients consume effective_limit instead of inventing their own log policy. Limit precedence is: explicit request.limit > logView override (services.<name> / all / global) > logs.bufferSize default.

Related docs

• Full protocol guide: Protocol
• Full config guide: Configuration

Session API

Endpoint	Method	Auth	Returns
/health	GET	Bearer token	{"ok": true} when server is live
/ws	GET (upgrade)	Bearer token	WebSocket session for protocol V1

Protocol Envelope

{
  "type": "<message_type>",
  "id": "<correlation_id>",
  "name": "<command_or_event_name>",
  "payload": {}
}

Type	Direction	Meaning
command	client -> server	Request runtime action or data
ack	server -> client	Immediate acceptance/rejection
result	server -> client	Final command outcome
event	server -> client	Async runtime updates
error	server -> client	Protocol-level error

High-Value Commands

• get_snapshot: full current service state.
• get_logs: log entries (service-scoped or all-services).
• start_service: start a named service.
• stop_service: stop a named service.
• restart_service: restart a named service.

Common CLI Forms

flowlayer-server -s 127.0.0.1:7010 -c ./services/flowlayer.jsonc
flowlayer-client-tui -addr 127.0.0.1:7010 -token "$FLOWLAYER_SESSION_TOKEN"
flowlayer-client-tui -config ./services/flowlayer.jsonc

First Checks for Integration Issues

• Token mismatch: verify server boot token vs client flag/config.
• Wrong address: verify bind/addr consistency and listening port.
• Stale assumptions: re-read snapshot before issuing control actions.

Useful next reads: How FlowLayer Works, Server, and Troubleshooting.