1 Introduction
Anton Nesterov edited this page 2026-11-06 18:44:31 +01:00

Introduction

VSKI is a swiss-knife backend server for agents and applications. One Go binary or one Docker image gives you typed collections, property graphs, full-text and vector search, realtime subscriptions, durable workflows, pipelines, cron, webhooks, plugins, authentication and access control, all behind a single REST API with Python and TypeScript SDKs and a CLI.

vski platform overview

Not just a document database

VSKI is often introduced as a document database, and it is one, but that is the least interesting part. It is the whole layer that teams usually assemble from parts: a database, a search index, a realtime channel, a job scheduler, an auth service, an admin dashboard. VSKI ships all of it in one server:

  • Collections with typed schema, relations, views and a filter language
  • Graphs with labelled nodes and weighted directed edges, no separate graph database needed
  • Search: full-text indexes (FTS5) and vector embeddings (sqlite-vec) with hybrid ranking
  • Realtime: subscribe to any collection over websockets and receive changes as they happen
  • Automation: durable workflows, trigger-driven pipelines, cron jobs and outbound webhooks
  • Plugins: supervised Python functions that run beside the server and are callable from pipelines
  • Auth: admins, users, API keys, JWTs, and a rule engine that compiles permissions into queries, down to single fields
  • Operations: migrations, Infrastructure-as-Code, replication, backup and a web dashboard

You point an SDK at it and the backend work is done. There is no second database to run, no message broker to babysit, no sync service to write between components that were never designed to talk to each other.

Performance, measured

Benchmark claims are cheap, so the repository ships a dockerized k6 harness that runs VSKI against minimal Go APIs over Postgres 17 and MySQL 8.4 on the same host, same scripts, open-model load. Numbers from the v0.17.0 release:

  • 10,000+ requests per second sustained in every scenario: point reads, creates, updates and mixed traffic, with zero errors
  • p95 of 0.40 ms on point reads; a mixed 80/20 read-write load holds a 0.67 ms p95 at 10,000 RPS, under 0.7 ms from 1,000 RPS up

In that company VSKI performs on the level of Postgres and MySQL for typical API traffic, from a storage engine that lives inside the server process. Methodology and reference numbers: BENCHMARK.md.

When VSKI outperforms

Raw throughput is only half the story. The architecture wins in the places where the classic stack pays a constant tax.

No network tax on the data path

A VSKI deployment is one server with one data directory. A request goes from the API handler straight into the storage engine: no database wire protocol, no socket hop, no driver round trip in between. Reads and writes land close to SSD speed. The same query against a client-server database pays the disk time plus a network exchange on every single request. Nothing is lost by keeping the data local, because distribution moves to where it is cheap: read replicas fan out for scale and double as live synchronized backup copies while the primary keeps writing at full speed.

One writer, one source of truth

An honest limit first: a VSKI instance does not scale out horizontally in the traditional sense. A database has exactly one writer at a time, by design. In practice most systems, including most microservice architectures, never need distributed writers. The databases that offer them pay for every write with distributed locks and consensus ledger traffic, and that cost grows as writers are added. VSKI skips the whole protocol: even in a multi-instance setup each database always has exactly one writer and one source of truth, so there is no coordination overhead to fund and no split-brain to defend against. When read volume grows, read replicas distribute the load.

A footprint you can run anywhere

Under a stable 2,500 RPS write load the server holds around 500 MB of memory. Idle, it sits at about 30 MB. Real workloads fit on small VPS boxes, home servers and edge machines that would embarrass a traditional database host, and a set of small services can share one box without anyone noticing.

Operations that stay flat

There is no cluster to configure, no tuning workbook, no scaling ceremony. Schemas are YAML files in the repository, applied with vski plan and vski apply, and every deployment looks the same, from a laptop to a fleet. One SDK covers almost everything a modern application or an agent needs, records, graphs, search, realtime, workflows, and drops down to SQL when you want it. VSKI was built to cut the effort between an idea and a running system, and to keep that effort flat as the requirements grow.

Why we committed to SQLite

People hear SQLite and picture phone apps and weekend scripts. In server usage, in WAL mode, with the connection handling done right, it is a different animal: no network hop, no separate database process, commits in microseconds. We committed to it for three reasons:

  1. It keeps up with the classic servers. The benchmark above is exactly this question, and VSKI answers it at 10,000+ RPS on every scenario, with sub-millisecond tail latency on reads and mixed traffic. A backend API is rarely limited by storage; it is limited by everything glued around it, and VSKI removes the glue.
  2. A database is a file. Backup is a file copy. A tenant is a file. Moving a deployment to new hardware is moving a directory. No dump and restore, no special tooling to learn before your first backup works.
  3. It deletes a whole service from the stack. No database server to install, secure, upgrade and monitor. VSKI owns its storage completely: pools, WAL lifecycle, checkpoints, group commit through the write queue.

And it scales along the whole range. The same binary runs on a home server or a small VPS and on production hardware under real load. When reads outgrow a single instance, add read replicas. When a server fills up, split databases across several. The API stays the same at every step, so scaling is an operations decision, never a rewrite.

What people build with it

  • Application backend. Web and mobile apps get a typed API, auth, access rules and realtime from one deployment.
  • Agent brain. Collections for facts and memory, graphs for relationships, vectors for semantic recall, pipelines for tool steps. The whole state of an agent in one place you can inspect, back up and reset.
  • Microservices backend. One uniform API contract and one SDK across all services, with the database layout left to operations (see below).
  • Multi-tenant SaaS. A tenant is a database: full isolation, per-tenant backup, restore and offboarding, one shared schema.
  • Automation and glue. Webhooks in, pipelines and workflows for the logic, cron for schedules, webhooks out to the other systems.
  • MCP services. Package domain logic as an MCP server on VSKI and hand agents a set of tools. See the MCP Server Tutorial.
  • Edge and homelab. One static binary, zero external dependencies, runs anywhere from a Raspberry Pi to the smallest VPS.

One API across microservices

Every VSKI deployment speaks the same REST contract and is managed the same way: same SDKs, same CLI, same declarative YAML, same dashboard. That uniformity is the point. In a microservice setup:

  • Every service talks to its data the same way. One SDK, learned once, used everywhere.
  • Lay it out as it fits: many databases on one server when services share hardware, or one database per instance when they scale apart. The API contract is identical in both shapes, so moving a service between them is a configuration change, not a port.
  • Deployments are boring: the same image everywhere, one IaC file per service, vski plan shows the diff before anything touches production.
  • Backup and restore are file operations, per service or for the whole server at once.

Multitenancy, pick your shape

VSKI does not force a tenant model. Databases are cheap, so tenancy is however you want to slice the system:

  • A tenant is an agent. Every agent instance gets its own database and its own memory, isolated from the fleet. Reset an agent by deleting one file, clone it by copying one.
  • A tenant is an organization. Classic SaaS: one database per customer with a shared schema, per-tenant backup and clean offboarding.
  • A tenant is a row. When per-tenant files are overkill, keep everyone in one database and let access rules decide who sees what.

When to choose traditional technologies

No tool fits every project, and a page that never admits its limits is marketing copy, not documentation. Two honest cases for the classic stack:

You want a vendor support line

VSKI is well documented and runs in any cloud, and the standard setup, one container with one data directory and file backups, is supported out of the box by most providers. What the public distribution does not include is humans: support is provided only to our clients, through SLA agreements, and the free distribution ships as is, with no support and no guarantees. If your team lacks the skills or the appetite to operate its own backend, a managed database from your cloud provider, hotline included, is the safer choice, and that is a perfectly good reason to make it.

You need everything open source

VSKI is not fully open source. It ships under the VSKI License: free to use for entities under $1M in revenue and capital raised, a commercial license above either threshold, and the core engine source is available to our clients under our disclosure and security policies. There is no plan to distribute the core as an open-source package today, partly because we focus on our clients, partly because we are not ready to carry an open-source community, with the feature requests and support load that come with one.

Is that a downside? We do not think so. You already run SaaS whose code you have never seen and cannot inspect. VSKI is easier to audit than any of it: the server never sends telemetry or any other data anywhere, and a single server with one data directory is simple to monitor, so any concern about data leaking can be settled by watching its network traffic. Our policy against leaking any sort of data is one of the points we keep under constant review.

Start