| name | remote-client |
| description | FlowLLM lite remote client operation guide. Use when a user asks Codex to run, inspect, monitor, or terminate commands through flowllm/lite/flow/remote_client_flow.py or the `fl --remote-client` CLI, including remote exec, ping, tasks, kill, kill_all, command files, Python files, timeout, host, port, and remote server troubleshooting. |
Remote Client
Overview
Use the FlowLLM lite remote_client flow to call a running remote_server over HTTP. Prefer it when work should execute on a configured remote project host instead of the local Codex shell.
The implementation lives in flowllm/lite/flow/remote_client_flow.py; the paired server endpoints live in flowllm/lite/flow/remote_server_flow.py.
Before Running
Confirm the target host and port before launching remote work:
fl --remote-client --action ping
If --host is omitted, remote_client_flow.py reads DEFAULT_REMOTE_HOST_ENV. If neither is set, it raises Remote host is required. Set DEFAULT_REMOTE_HOST_ENV or pass --host.
Use --host only when overriding DEFAULT_REMOTE_HOST_ENV. Use --port only when the server is not on the default 8765.
Actions
Run a shell command remotely and stream stdout/stderr back to the local terminal:
fl --remote-client --action exec --command "pytest tests/unit"
Run a command stored in a local file:
fl --remote-client --action exec --command-file /path/to/command.sh
Upload and run a local Python file on the remote server:
fl --remote-client --action exec --python-file /path/to/script.py
Inspect tracked remote tasks:
fl --remote-client --action tasks
fl --remote-client --action tasks --status running --tail 80
Terminate a task or all running tasks:
fl --remote-client --action kill --task-id 12
fl --remote-client --action kill_all
Parameters
--action: one of exec, ping, tasks, kill, kill_all; default is exec.--host: remote host. Falls back to DEFAULT_REMOTE_HOST_ENV.--port: remote server port; default is 8765.--timeout: command timeout in seconds; default is 3600.--command: shell command string for exec.--command-file: local text file whose contents become the remote shell command.--python-file: local Python file uploaded as code and run by the remote Python interpreter.--status: optional task status filter for tasks, commonly running, finished, or killed.--tail: output lines to include per task for tasks; default is 30.--task-id: required for kill.
For exec, provide exactly one of --command, --command-file, or --python-file.
Remote Server Assumptions
The client expects the server to expose:
GET /pingGET /tasksPOST /execPOST /tasks/{task_id}/killPOST /tasks/kill-all
The remote server executes shell commands with cwd set to FLOWLLM_REMOTE_PROJECT_DIR when that environment variable is set, otherwise the server process working directory. Python-file execution prepends that project directory to PYTHONPATH.
Troubleshooting
When connection fails, verify fl --remote-client --action ping first, then check that DEFAULT_REMOTE_HOST_ENV is set and remote_server is running and reachable from the local machine.
If a streamed command disconnects, inspect remote state with:
fl --remote-client --action tasks --status running
For long or multi-line commands, prefer --python-file or --command-file over complex shell quoting.
After a timeout, the server writes [TIMEOUT] to the stream and attempts to terminate the remote process group.
