Skip to main content

Remote Server Session

This distributed use case runs FlowLayer on a remote VM or shared machine while you operate the runtime from your local terminal.

This is useful when services are heavy for a laptop but you still want interactive control through the official TUI.

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.