Skip to content

Getting Started

This guide takes you from a fresh machine to a running vornik daemon with your first project, then submits and watches a task run end to end. It assumes no prior vornik knowledge — if a term is unfamiliar, the Concepts page explains the vocabulary.

What vornik does

vornik is an asynchronous orchestration daemon. You define projects, each backed by a swarm of agents and one or more workflows. You submit tasks; vornik queues them, starts the agents in isolated local containers, runs them through the workflow, and persists the results. Work runs continuously in the background — you submit and walk away, then come back for the output.

You can drive it from the CLI, the HTTP API, the Web UI, or a connected conversation channel (a Telegram bot or email). Around the core, recent releases add operability and resilience features you will meet later in the docs — a one-command redacted support bundle, expanded vornikctl doctor checks, centralised log forwarding, structured recovery for failed steps, and a bounded graceful shutdown — plus security hardening for running the daemon behind a reverse proxy. None of that is needed to get started; the defaults are safe and local-first.

Prerequisites

  • Go 1.25+ — to build the daemon and CLI from source.
  • Podman (rootless recommended) — vornik runs every agent in its own Podman container for isolation. Docker is not used.
  • PostgreSQL with the pgvector extension — vornik keeps all durable state (queues, tasks, executions, artifacts, memory) in PostgreSQL so work survives restarts. pgvector backs the memory/RAG semantic search — the recommended pgvector/pgvector image ships it, and vornik enables the extension on first boot. SQLite is supported for the orchestration core, but it cannot do vector search, so memory/RAG falls back to keyword search only (see Memory & RAG).
  • Make — convenience build targets.

Note

vornik is local-first: the daemon and all agent containers run on the same host. There is no cloud service to sign up for.

A 60-second playground

Preferred: AI-assisted install

If you use a coding agent (Claude Code, Codex, Gemini CLI, …), let it do everything on this page for you — paste this into your agent:

Set up Vornik for me. Follow the runbook at https://agents.vornik.io

AGENTS.md is an agent-executable runbook: install (via the same get.vornik.io script below), LLM key setup, a first task, and the agent's own companion project + persistent RAG memory + knowledge-skill store (so it can capture reusable procedures and reuse them across sessions and projects) — with a verifiable check at every step, and your approval required before anything privileged.

If you'd rather run it yourself, one command stands up a complete playground on a Linux host. It installs any missing prerequisites, builds the daemon + CLI in an ephemeral container (no Go toolchain needed), starts PostgreSQL + pgvector in a container, and runs the daemon as a rootless systemctl --user service that spawns agent containers via your rootless Podman:

curl -fsSL https://get.vornik.io | bash

This pins the release tag baked into the script (not a moving branch); set VORNIK_REF=main for bleeding-edge. To verify the script against its published checksum before piping it to a shell (catches transit/redirect tampering — not a signature), fetch both first:

REF=<release>  # a tag from github.com/EaseIT-cz/vornik/releases that ships quickstart.sh.sha256
base="https://raw.githubusercontent.com/EaseIT-cz/vornik/$REF/deployments/podman"
curl -fsSLO "$base/quickstart.sh" && curl -fsSLO "$base/quickstart.sh.sha256"
sha256sum -c quickstart.sh.sha256 && VORNIK_REF="$REF" bash quickstart.sh

The daemon creates and migrates its own schema on first boot, so all you supply is an empty database — the script provisions it. When it finishes, open http://localhost:8080/ui and log in with the API key the installer generated (VORNIK_API_KEY in ~/.config/vornik/secrets/api.env; every request needs it). A first-run setup guide walks you through connecting an LLM endpoint and key (with a live connection test), optional memory/RAG, and creating your first project. To do the same from the terminal, set VORNIK_CHAT_API_KEY in ~/.config/vornik/vornik.env and run systemctl --user restart vornik. See the Podman deployment notes for tunables and the runtime model.

This is the fastest way to get a working instance; the rest of this page builds the same thing by hand so you understand each piece.

Install

Build the two binaries from source:

# The daemon
go build -o bin/vornik ./cmd/vornik

# The control CLI
go build -o bin/vornikctl ./cmd/vornikctl

Or use the Make target, which produces the same binaries:

make build

Put bin/ on your PATH (or call the binaries by path). The rest of this guide assumes vornik and vornikctl are on your PATH.

Confirm the build:

vornik --version
vornikctl version

vornik --version reports the build you are running; building from the latest main may report a newer version than the most recent tagged release. See the Release notes for what each release adds.

Point vornik at a database

vornik reads its database connection from configuration or environment variables. The quickest path is environment variables:

export VORNIK_DATABASE_HOST=localhost
export VORNIK_DATABASE_PORT=5432
export VORNIK_DATABASE_NAME=vornik
export VORNIK_DATABASE_USER=vornik
export VORNIK_DATABASE_PASSWORD=vornik

vornik creates and migrates its schema on first start, so an empty database is all you need — point it at a fresh database and let it migrate; do not pre-load a schema dump. Use a PostgreSQL image with pgvector (e.g. pgvector/pgvector) so the memory/RAG vector search works; vornik enables the extension during that first-boot migration. For a full list of settings and the YAML equivalent, see the Configuration reference.

Start the daemon

vornik

With no flags, vornik looks for configuration in this order: the --config flag, the VORNIK_CONFIG environment variable, ./vornik.yaml (or ./config.yaml), ~/.config/vornik/ (XDG user config), then /etc/vornik/vornik.yaml. To run with an explicit file:

vornik --config /path/to/vornik.yaml

Once it is up, the daemon serves a Web UI and an HTTP API (default :8080). Check it is ready before submitting work:

curl http://localhost:8080/readyz
# {"status":"ready","checks":[{"name":"database","status":"ok"}]}

A 200 from /readyz means every dependency the daemon needs is reachable. A 503 lists which check is failing — see Troubleshooting if you get one.

Create your first swarm

A project needs a swarm to run on. The fastest way to get one is to generate it from a built-in preset. The research preset (a lead plus a researcher and a writer) is a good fit for digest, scan, and summary-style work:

vornikctl init swarm my-swarm --template research

To see every preset and a one-line description of each:

vornikctl init swarm --list

This writes a SWARM.md file into your configs/swarms/ directory and validates it against the registry before saving.

Create your first project

Generate a project that uses the swarm you just created and the built-in adaptive workflow:

vornikctl init project my-project \
  --display-name "My First Project" \
  --swarm my-swarm \
  --workflow adaptive

Pass --dry-run first if you want to preview the generated YAML without writing it. The command validates the project against the registry — it will refuse to create a project that references a swarm or workflow that does not exist.

Note

You can also create projects without touching the CLI: open the Web UI at /ui/projects/new for a gallery of templates, or /ui/projects/new/wizard for a conversational wizard that composes a base template with typed add-ons (MCP servers, schedule, secrets, tools, role instructions) and builds the project, swarm, and workflow for you.

A project runs one autonomy style. If you describe a need with two cadences — say, "ingest my mail every 5 minutes and produce a daily digest" — the wizard builds a single scheduled loop whose goal handles both (frequent ingestion each tick; the digest when the day's elapsed), rather than two conflicting schedules. Set chat.wizard_model to a capable model (a strong Bedrock chat model works well) if you want higher-quality drafts; the wizard still converges on a valid project regardless of the model.

Confirm the daemon has loaded your project:

vornikctl project list
vornikctl project show my-project

However you created it, every project gets a readiness checklist at /ui/projects/{id}/setup — config, secrets, MCP reachability, chat model, schedule, and an optional smoke test — and the project list flags any project with unmet required checks.

Submit your first task

Now submit a task. The --prompt flag is the simplest way to describe the work:

vornikctl task submit \
  --project my-project \
  --prompt "Summarise the key themes in the attached notes."

The command returns a task ID. vornik has queued the task; the scheduler will pick it up, start the agents, and run them through the project's workflow.

Useful options:

  • --priority <0-100> — lower numbers run first; 0 uses the project default.
  • --workflow <id> — run this task on a workflow other than the project default.
  • --task-type <label> — a free-form label that shows up in the task list.
  • --attach <file> — attach a file as an input; it is snapshotted and extracted into project memory so agents can read it.
vornikctl task submit -p my-project \
  --prompt "Review this report and list open risks." \
  --attach report.pdf \
  --priority 10

Watch it run

List the tasks in your project, optionally filtered by status:

vornikctl task list --project my-project
vornikctl task list --project my-project --status RUNNING

Inspect a single task — its status, workflow, and timestamps:

vornikctl task get <taskId> --project my-project

Follow the live logs while it runs, or read the result excerpt once it has finished:

vornikctl task tail <taskId> --project my-project --follow

A task moves through PENDING → QUEUED → RUNNING and ends in COMPLETED, FAILED, or CANCELLED. When it completes, any files the agents wrote as outputs are persisted as artifacts and surfaced through the API and Web UI.

Where to go next