Start a worker from the registry (and upgrade it)¶
Goal: create a worker of a known type (e.g. BinanceOrderBook, TradeFlow,
HttpGet), start it, and later load a newer (or older) version of its package.
Prerequisites
- An active context (Switch context).
- The worker type is in the worker registry: the catalog shipped with the TUI
(synced from general-workers with each release, e.g.
HttpGet,EventStore,WebSocketFeed,BinanceOrderBook,BinanceTrades,BinanceCandles,AlpacaOrderBook,MovingAverageCrossover,TradeFlow,BookImbalance,PnL,SimulatedExecutor, ...) merged with your own~/.config/virtufin/tui/workers.toml(your entries override the shipped one of the same name, field by field). - A worker that needs credentials: the key of the cluster's worker Secret
(
virtufin-worker-secrets) holding them.
Create and start¶
- Open Workers: Infra top tab,
1(Workers) in the default layout. - Add: press
a. In New Worker — pick a type, highlight the type,Enter. - Fill in the form (built from the entry's config schema):
- Topics — comma-separated, pre-filled where the registry gives them. Templates
such as
act.exchange.binance.trade.update.{pair}expand from the config ({pair}fromcurrencypairs,{interval}fromintervals); theworldconfig re-bindsacttohyp.<NAME>. - The config fields.
- Secret … (reference) — the key in the worker Secret, never the secret.
- Topics on create below the form shows the expanded topics as you type.
- Topics — comma-separated, pre-filled where the registry gives them. Templates
such as
- Create: press Create. Toast:
Created worker (<type>). The worker is taggedtype=<type>andsource=<code URL>and is not started yet. - Start: highlight its row, press
m, choose Start Worker.
Upgrade (or roll back)¶
- On Infra › Workers, highlight a worker made from a versioned registry package. The status line counts the workers that have a newer version.
- Press
u. Upgradeshows the current version; pick one in the list (the newest is preselected; an older one rolls back) and press Load. - Toast:
<name>: <old> -> <new>, restarting with the new code. The worker keeps its id, topics, config, secrets and tags; a running one stops, loads the code and starts again (its in-memory state starts fresh).
Several at once: mark rows with space (or filter with /), press b, choose the
upgrade to the latest version; a report lists each worker's result.
What you should see¶
- The new row with its Name (the
typetag), Topics, Config and Secrets (references only); its status changes to running after Start. Enteron the row opens its detail: last load or start error, lifecycle events since the TUI connected, tags, config, code history.- Every change is recorded on Infra › Changes.
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
No worker types in registry (~/.config/virtufin/tui/workers.toml) |
The registry is empty; reinstall the TUI or add entries to your workers.toml. |
Create is refused, Topics: ... |
A placeholder has no value (e.g. intervals unset) or a pair is malformed (btcusdt instead of BTC_USDT), or the world is not act/hyp.<NAME>. |
Validation errors: ... |
A form field fails the entry's config schema. |
The worker shows LOAD_FAILED |
A missing secret key, or the code could not load; Enter shows the error. |
<name>: not a versioned package of the worker registry, nothing to load on u |
The worker was not created from a {version} registry entry (e.g. inline code); recreate it from the registry. |
| A newer version is not offered | The registry lists versions statically: upgrade the TUI, or add the version to your entry's versions in workers.toml. |
The AI tab can do the same: registry__list, workers__create, workers__start,
workers__upgrade (The TUI's API). Reference:
Keybindings › Workers.