Skip to content

Get Started

The shortest path to a running worker. Each step points at the page that owns the details.

1. Pick an API: shared cluster or local stack

Every example talks to one Virtufin API, named by a context. An example sets the name as a constant near its top:

// The context: a name in ~/.config/virtufin/api/contexts.toml.
// "demo" is the shared cluster (needs an API key); "local" is a stack you run yourself.
const string ContextName = "demo";

The name is looked up in ~/.config/virtufin/api/contexts.toml, which holds each context's host, port, TLS flag and API key. The examples Getting Started shows the file and the demo and local entries.

To run the backend yourself (the local context, gRPC on localhost:5002), follow the deploy-local README: it starts the API gateway and the WorkManager natively with dapr run against a local Redis (scripts/deploy.sh). See Operations for the other deployment modes.

2. Call the API

The API gateway is gRPC only. Its client libraries are built from the api repo:

Language Package Guide
C# / .NET Virtufin.Api.Client (NuGet) C# SDK
Python virtufin-api (PyPI) Python SDK
TypeScript @virtufin/api (npm) TypeScript SDK

To browse the RPCs interactively, see the gRPC API Explorer.

3. Run a sample worker

The general-workers walkthrough builds, publishes and deploys HttpGet, the canonical sample worker (GetTime and Hello live next to it). A worker's command topic comes from the naming library: wrk.httpget.command.<worker_id> for HttpGet.

To write your own worker, start with the Worker DevKit and the Engine System page, which explains which engine to use.

4. Read the spec

For anything that needs to be exact (topic naming, scenario registry semantics, state keys, the worker wire contract), the spec is the answer: