Skip to content

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

  1. Open Workers: Infra top tab, 1 (Workers) in the default layout.
  2. Add: press a. In New Worker — pick a type, highlight the type, Enter.
  3. 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} from currencypairs, {interval} from intervals); the world config re-binds act to hyp.<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.
  4. Create: press Create. Toast: Created worker (<type>). The worker is tagged type=<type> and source=<code URL> and is not started yet.
  5. Start: highlight its row, press m, choose Start Worker.

Upgrade (or roll back)

  1. On Infra › Workers, highlight a worker made from a versioned registry package. The status line counts the workers that have a newer version.
  2. Press u. Upgrade shows the current version; pick one in the list (the newest is preselected; an older one rolls back) and press Load.
  3. 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 type tag), Topics, Config and Secrets (references only); its status changes to running after Start.
  • Enter on 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.