Skip to content

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 contexts table at the top of the Navigation pane (Config › Navigation in the default layout; Switch context step by step). Highlight a context and press Enter to make it active. The TUI first checks that the context's api answers (one keyed call); only then does it switch: the new context is saved as the active one, the current gRPC channel closes and new ones open, and the dashboard refreshes within 1 second. A context that does not answer (or refuses the key) is reported as a toast, and the current one stays active. A switch prepares the new context as startup does: scenario.LIVE is created when it is missing, and your init_scripts run against it.

The context row under the tab bar names the active context on every tab (Trading adds the Scenario), so no action runs without the context in sight.

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, the one --context or VIRTUFIN_TUI_CONTEXT names when set (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 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 reads for its 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 HttpGet 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.
description Free-form label shown in the picker (e.g. "Production — last deploy 2026-07-05").
protected true for a context where a mistake costs (production). Its context row is red on every tab (PROTECTED: changes ask first), and every change the TUI makes there asks first in a dialog: creating, deleting, starting and stopping workers and setting their tags, worker commands other than status, state saves and deletes, scheduling and deleting triggers — from the pages, their dialogs and the AI tab alike. After a yes, the further changes of the next 5 s go through without asking (one action is often several calls); a no leaves everything as it was. Scripts run as their own processes and are not covered.

An entry without name, api_host or api_port (or with a port that is not a number), or a file that is not valid TOML, does not stop the TUI: the entry is skipped and the problem is shown when the TUI starts (and logged).

No active context

If no context is active -- for example the stored active_context names a context that no longer exists in contexts.toml, or the file was never created -- the TUI does not exit. It starts on the Config page, lists every configured context, and shows each one as not connected (red). No endpoint is watched while unbound. Every other pane but Home says it needs a context until one is picked. Highlight a context and press Enter to connect; from then on the normal lifecycle (including each context's liveness watch) resumes. With no contexts configured at all, the Config page shows no contexts configured in <path> and nothing to switch to.

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. The dots are pushed, not probed: each context has one gRPC health stream (grpc.health.v1.Health/Watch) whose status the api pushes when it changes, on a channel whose keepalive pings notice a dead path. liveness_keepalive_seconds in config.toml sets the ping interval (default 20): a silently dead connection turns red after about that plus 10 s; 0 turns liveness off. Each time a context comes up, one keyed call checks its API key. Switching context also validates the new connection immediately, so a bad key on the target context is reported right away as a toast. 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.