Skip to content

Getting started

Open the app

The app is deployed at https://app.virtufin.com. There is nothing to install: open it in a current browser (desktop or phone; at phone width the sidebar folds behind the ☰ button in the header).

Sign in

Signed out, the app shows only its sign-in page (Sign in to see the platform's workers, worlds and scenarios.) and a Log in button. Log in sends you to the organisation's identity provider (Pocket ID on medusa); after you sign in there you come back to the page you started from.

  • A sign-in lasts 12 hours by default (VIRTUFIN_APP_SESSION_HOURS on the server); after that the app asks you to log in again.
  • The header shows your name, a badge and Log out. Log out ends the session.
  • If the provider takes longer than 10 minutes to send you back, the sign-in is refused (the sign-in took too long or was not started here; sign in again): log in again.

Roles: who may write

You are You may
Signed in (any member) Read everything: every view, every list, every stream. The badge says read only; buttons that change something are disabled, with the tooltip Only admins may ….
A member of the admin group (virtufin-admins by default, VIRTUFIN_APP_ADMIN_GROUP on the server) Also write: start, stop, create, delete, tag, schedule, share, halt, … The badge says admin.

The app server enforces this, not only the buttons: a write from a non-admin is refused with 403 only admins may write whatever sends it (a view, a script, the assistant). See Architecture for how the server tells a read from a write.

Your admin membership is read when you sign in: after a change in the provider's groups, log out and in again.

The context menu

Everything you see and do is on one context: one virtufin-api endpoint (for example demo). The context menu, top right in the header, names the active context with a health dot (green up, yellow connecting, red down or key refused). Click it to see every context, its health, its description and whether it is protected, and to switch. On a protected context the button is red and says protected: writes ask first. See Contexts.

First steps

  1. Home lists the views this app has for the navigation in use and the active context's state (Context demo: up.).
  2. Infra > Workers lists the context's workers, live. Type in the filter, e.g. status:running or tag:world=act; click a row and press Detail (or Enter) for its config, tags, code history and lifecycle events.
  3. Trading > Scenario shows the scenarios and their trading halt; Use picks the scenario P&L and Risk follow in this browser.
  4. Infra > Events → Topics… to follow some topics and watch their CloudEvents arrive.
  5. Settings > AI to add an AI provider key; then AI in the header opens the assistant on every view (Set up AI).

The How-tos walk through the common tasks.

For developers: run it locally

The app is a Vue 3 frontend with a small Node server side (the context proxy, sign-in, the AI relay and the change log). Locally the Vite dev server runs the same server side as a plugin.

cd src/VirtufinApp
npm install          # @virtufin/* come from the Gitea npm registry (.npmrc, token from VIRTUFIN_REGISTRY_TOKEN)
npm run dev          # http://localhost:3000

The contexts come from ~/.config/virtufin/api/contexts.toml, the same file the TUI and the notebooks read (VIRTUFIN_CONTEXTS_FILE names another). Pick the starting context with VIRTUFIN_CONTEXT:

VIRTUFIN_CONTEXT=demo npm run dev

A minimal contexts.toml:

[[contexts]]
name = "demo"
description = "medusa demo"
api_host = "api.virtufin.com"
api_port = 443
tls = true
api_key = "..."          # or VIRTUFIN_API_KEY in the dev server's environment
protected = false

Without the sign-in settings (VIRTUFIN_APP_OIDC_ISSUER and the others, see Architecture) the dev server signs no one in and everyone is an admin: the header shows no sign-in (dev). With them set, the dev server signs in as the deployed one does.

scripts/run_app.sh starts the backend (api, WorkManager) through the sibling deploy-local repo and the frontend together. Build, typecheck and tests are in the repo README (docs/README.md).