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.