Rename CF_ORCH_URL to GPU_SERVER_URL for self-hoster clarity #9

New issue

Open

opened 2026-05-17 09:39:04 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-05-17 09:39:04 -07:00

Owner

Summary

Follow the GPU_SERVER_URL convention established in kiwi (see kiwi commit on config.py).

CF_ORCH_URL is the internal cf-orch env var name but is not self-explanatory for a local-first user setting up their own GPU rig. Rename the user-facing env var to GPU_SERVER_URL, keeping CF_ORCH_URL as a backward-compat alias.

Pattern (from kiwi `app/core/config.py`)

GPU_SERVER_URL: str | None = (
    os.environ.get("GPU_SERVER_URL")
    or os.environ.get("CF_ORCH_URL")          # backward-compat alias
    or (
        "https://orch.circuitforge.tech"
        if os.environ.get("CF_LICENSE_KEY")   # Paid+ auto-default
        else None
    )
)

Then after settings = Settings():

if settings.GPU_SERVER_URL:
    os.environ["CF_ORCH_URL"] = settings.GPU_SERVER_URL

This propagates the resolved URL back into os.environ["CF_ORCH_URL"] so all existing service-layer callers (os.environ.get("CF_ORCH_URL")) continue to work without changes.

Files to update

app/core/config.py (or equivalent settings file): add GPU_SERVER_URL with priority chain above
.env.example: replace CF_ORCH_URL=... example with GPU_SERVER_URL=...; note CF_ORCH_URL is still honoured
Any compose files that pass CF_ORCH_URL: add GPU_SERVER_URL as the documented name (keep CF_ORCH_URL for compat)

Notes

CF_ORCH_URL must remain supported (it is read directly by cf-core internals and CFOrchClient)
The os.environ write-back trick means no service files need updating, only config/settings
Free tier: no orch URL unless user sets one (BYOK or local rack)
Paid+: auto-defaults to https://orch.circuitforge.tech when CF_LICENSE_KEY is present

## Summary Follow the `GPU_SERVER_URL` convention established in kiwi (see kiwi commit on config.py). `CF_ORCH_URL` is the internal cf-orch env var name but is not self-explanatory for a local-first user setting up their own GPU rig. Rename the **user-facing** env var to `GPU_SERVER_URL`, keeping `CF_ORCH_URL` as a backward-compat alias. ## Pattern (from kiwi `app/core/config.py`) ```python GPU_SERVER_URL: str | None = ( os.environ.get("GPU_SERVER_URL") or os.environ.get("CF_ORCH_URL") # backward-compat alias or ( "https://orch.circuitforge.tech" if os.environ.get("CF_LICENSE_KEY") # Paid+ auto-default else None ) ) ``` Then after `settings = Settings()`: ```python if settings.GPU_SERVER_URL: os.environ["CF_ORCH_URL"] = settings.GPU_SERVER_URL ``` This propagates the resolved URL back into `os.environ["CF_ORCH_URL"]` so all existing service-layer callers (`os.environ.get("CF_ORCH_URL")`) continue to work without changes. ## Files to update - `app/core/config.py` (or equivalent settings file): add `GPU_SERVER_URL` with priority chain above - `.env.example`: replace `CF_ORCH_URL=...` example with `GPU_SERVER_URL=...`; note CF_ORCH_URL is still honoured - Any compose files that pass `CF_ORCH_URL`: add `GPU_SERVER_URL` as the documented name (keep `CF_ORCH_URL` for compat) ## Notes - `CF_ORCH_URL` must remain supported (it is read directly by cf-core internals and CFOrchClient) - The os.environ write-back trick means no service files need updating, only config/settings - Free tier: no orch URL unless user sets one (BYOK or local rack) - Paid+: auto-defaults to `https://orch.circuitforge.tech` when `CF_LICENSE_KEY` is present

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Circuit-Forge/pagepiper#9

No description provided.

Rename CF_ORCH_URL to GPU_SERVER_URL for self-hoster clarity #9

Summary

Pattern (from kiwi app/core/config.py)

Files to update

Notes

Pattern (from kiwi `app/core/config.py`)