Contexts

virtufin-tui supports multiple virtufin-api endpoints ("contexts") so you can operate against dev, staging, and prod from the same session.

See Getting started for the contexts.toml schema and the XDG-aware file path.

Switching

Go to the Config tab (Infra → Config by default). Highlight a context and press Enter to make it active. Switching closes the current gRPC channel and opens new ones; the dashboard refreshes within 1 second.

Programmatic override

For one-off overrides without editing contexts.toml, set the env var VIRTUFIN_TUI_CONTEXT=name. The TUI starts with that context active, ignoring the stored active-context state (see Persistence below).

VIRTUFIN_TUI_API_HOST and VIRTUFIN_TUI_API_PORT override the host/port of the active context (useful for ad-hoc connections to a port-forwarded gRPC server).

Per-context settings

Field	Purpose
tls	Use TLS for the gRPC channel, verified against the system CA roots. Required for endpoints behind a TLS-terminating ingress; recommended for any non-localhost endpoint.
api_key	Sent as x-api-key metadata on every call. Required when the endpoint enforces API-key auth (the cluster ingress does); keys are provisioned per user in the API's ApiAuth:Keys config — an admin runs python scripts/provision_api_key.py <username> in the virtufin-api repo to generate one and give it to you out-of-band. The file's 0600 mode protects the stored key. If a context has no api_key set, the VIRTUFIN_API_KEY env var is used instead (same variable name workmanager/websocketmanager read for their own outbound calls to the gateway) — useful for CI or a shared shell profile without putting the key in contexts.toml. An inline api_key always wins over the env var when both are set.
worker_api_host	The address a worker (a separate process the WorkManager spawns — e.g. the WebSocketManagerController example — not this TUI) must dial for its own callback connection to the virtufin-api Gateway. Defaults to api_host when unset. Set this when the worker runs somewhere api_host isn't reachable from — e.g. api_host is a TLS-terminating ingress address reachable only from outside the cluster, but the worker runs inside the cluster and needs a plaintext, cluster-internal address such as api.virtufin.svc.cluster.local.
worker_api_port	Port for worker_api_host. Defaults to api_port when unset.
default_worker_topic	If set, the events panel auto-subscribes to this topic on context start. Defaults to subscribing to the topic from the currently-highlighted row.
description	Free-form label shown in the picker (e.g. "Production — last deploy 2026-07-05").

Connection status & errors

Every context row in the Config page shows a colored dot: green (reachable), red (not reachable), grey (not checked yet). The Home page's connection line shows the same dot for the active context. On a red dot, the specific reason is shown next to it — e.g. Invalid or missing API key (bad/missing api_key, distinct from other failures), Server unavailable (check host/port/network), or the raw gRPC status for anything else. Switching context also validates the new connection immediately (rather than waiting for the next liveness check), so a bad key on the target context is reported right away as a toast instead of surfacing only once the periodic check catches up. The Key column shows where the effective key comes from: cfg (contexts.toml), env (VIRTUFIN_API_KEY), or -- (none configured).

Persistence

contexts.toml holds only the context definitions -- which context is currently active is state, not config, and lives separately at ~/.local/state/virtufin/api/state.toml ($XDG_STATE_HOME-aware, same convention as $XDG_CONFIG_HOME for contexts.toml). Switching context from the Config page writes active_context = "<name>" there immediately. The file is created with mode 0600.