Remote Server Session

Use this when the stack is too heavy for your laptop but you still want interactive control through the official TUI.

flowlayer-server runs on a VM or shared dev host; the TUI on your laptop connects over the Session API, observes runtime state, and sends commands as if the stack were local.

Remote server config

{
  "session": {
    "bind": "0.0.0.0:6999",
    "token": "remote-dev-token"
  },
  "services": {
    "postgres": {
      "cmd": ["postgres", "-D", "/srv/flowlayer/var/postgres"],
      "port": 5432,
      "ready": {
        "type": "tcp"
      }
    },
    "redis": {
      "cmd": ["redis-server", "/srv/flowlayer/infra/redis.conf"],
      "port": 6379,
      "ready": {
        "type": "tcp"
      }
    },
    "api": {
      "cmd": ["pnpm", "--dir", "services/api", "dev"],
      "dependsOn": ["postgres", "redis"],
      "port": 3000,
      "ready": {
        "type": "http",
        "url": "http://127.0.0.1:3000/health"
      }
    },
    "worker": {
      "cmd": ["pnpm", "--dir", "services/worker", "dev"],
      "dependsOn": ["api", "redis"]
    }
  }
}

Start on the remote host:

ssh dev@10.42.0.21 "cd /srv/flowlayer && flowlayer-server -c ./flowlayer.jsonc"

Connect from your laptop

Direct LAN or VPN connection:

flowlayer-client-tui -addr 10.42.0.21:6999 -token remote-dev-token

Or keep a local TUI config:

{
  "session": {
    "addr": "10.42.0.21:6999",
    "token": "remote-dev-token"
  }
}

flowlayer-client-tui -config ./flowlayer.remote.tui.jsonc

Safer pattern: SSH tunnel

Instead of exposing the session port broadly, forward it:

ssh -L 6999:127.0.0.1:6999 dev@10.42.0.21

Then connect the TUI locally:

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

Security checklist

• Keep the session endpoint on private networks, VPN, or SSH tunnel.
• Use long, unique session tokens per environment.
• Rotate tokens when shared machine access changes.
• Restrict inbound access to the session port with host firewall rules.
• Never expose remote dev session endpoints directly to the public internet.

See Server and TUI Modes for server and client address semantics.

Boundaries

• This setup is for development and test environments.
• FlowLayer does not replace production service managers or cluster orchestrators.
• Keep production controls in Kubernetes, Docker Compose automation, PM2, systemd, or equivalent tools where they belong.