Explicit compute URL

Setting --compute-url or DF_COMPUTE_URL pins a specific URL and disables Auto routing. The pinned URL is used for every query until /use-node auto re-enables Auto.

Syntax

--compute-url <URL>  |  DF_COMPUTE_URL=<URL>

Description

## Overview Explicit compute URL mode pins the CLI to a specific worker endpoint, bypassing the control plane's routing logic. Use it when you want deterministic behaviour against one worker, for reproducing a failure observed on a specific node, for isolating a benchmark run, or in environments where the control plane is not reachable from the client. ## Behavior - Setting `--compute-url <URL>` on the command line, `DF_COMPUTE_URL=<URL>` in the environment, or `compute_url = "<URL>"` in the active profile sets `compute_url_explicit=true` and `compute_url_auto=false`. - Every SQL call is sent directly to the pinned URL. No `/nodes/recommend` call is made per query, removing the per-statement control plane round trip. - The URL is used verbatim. It is not validated against `/list-compute-nodes` and is not checked against the control plane's node registry. - Precedence: command-line `--compute-url` overrides `DF_COMPUTE_URL`, which overrides a profile `compute_url` value. - Inside the REPL, `/use-node auto` clears the explicit pin for the session and returns to Auto routing. `/use-node <name>` replaces the explicit URL with a name-resolved pin. ## Compatibility - An explicit URL works without a running control plane, which makes it useful for direct worker access during incident response or local development against a single `df-server` process. - Authentication still flows through the normal CLI auth path; only the compute dispatch target changes.

Examples

delta-forge-cli --compute-url http://worker-01:3031

DF_COMPUTE_URL=http://worker-01:3031 delta-forge-cli

# Profile pinning via config.toml
[profiles.production]
compute_url = "http://worker-01:3031"

Pitfalls

• An explicit URL skips `/list-compute-nodes`, so if the URL is wrong or the worker is down, queries fail rather than failing over to another healthy node. Auto routing would pick a different worker.
• A profile that sets `compute_url` puts the shell in pinned mode from the very first statement. Users expecting Auto routing need to omit `compute_url` from the profile or run `/use-node auto` after launch.
• The URL is not validated at startup. A typo in the hostname or port only surfaces when the first query is issued and the HTTP request fails.

See Also

• CLI_COMPUTE_AUTO
• CLI_FLAG_COMPUTE_URL
• CLI_ENV_COMPUTE_URL