Skip to content
VSKI

Getting Started

From nothing to a running VSKI server with a collection, a record and a pipeline-ready declarative project. All you need is Python 3.11+ and Docker.

Quickstart

Section titled “Quickstart”

1. Install the command line tool

Section titled “1. Install the command line tool”
Terminal window
pip install "vski-sdk[cli]" --extra-index-url https://vski.sh/api/packages/x/pypi/simple/

This gives you the vski command, which manages everything: the local server, the deployment and declarative config. Check your environment any time with:

Terminal window
vski doctor

2. Start a local server

Section titled “2. Start a local server”
Terminal window
vski install          # pulls vski.sh/x/vski:latest-standalone via docker
vski serve            # runs it on http://127.0.0.1:3000 (Ctrl-C stops it)

vski serve keeps data in ~/.vski/data and generates a persistent JWT_SECRET in ~/.vski/serve.env, so tokens survive restarts. Prefer it in the background? vski serve --detach. Different port or data directory? vski serve 3001 /path/to/data.

3. Create the first admin

Section titled “3. Create the first admin”

Open the installer in your browser:

http://127.0.0.1:3000/installer

Create the admin account, then let the command line tool remember it:

Terminal window
vski login            # prompts for email + password, stores the JWT
vski status           # health + effective config

For scripts and CI, mint an API key instead and export it:

Terminal window
vski keys create dev --roles admin     # raw key printed exactly once
export VSKI_API_KEY=vski_...

4. Set up a project and apply it

Section titled “4. Set up a project and apply it”

Schema lives in YAML, not in imperative calls (see IaC):

Terminal window
vski setup            # scaffolds ./vski with a starter notes collection
vski plan             # shows what apply would change (exit code 2 on drift)
vski apply --yes      # creates the collection via a server-side migration

The scaffold ships a working notes collection plus commented pipeline, cron and secrets examples. Put it in git from day one.

5. Use it

Section titled “5. Use it”
Terminal window
vski records create notes '{"title": "hello", "body": "it works"}'
vski records list notes

Or from Python (the same SDK the command line tool is built on):

import asyncio
from vski import VskiClient


async def main():
    async with VskiClient("http://127.0.0.1:3000") as client:
        res = await client.admins.auth_with_password(
            "admin@yourdomain.com", "your-password"
        )
        client.set_token(res["token"])


        record = await client.collection("notes").create(
            {"title": "hello", "body": "from the SDK"}
        )
        print(record["id"])


        page = await client.collection("notes").get_list(
            1, 30, filter='title ~ "hello"'
        )
        for item in page["items"]:
            print(item["title"])


asyncio.run(main())

Installation details for Python and TypeScript live on the SDK Installation page.

Manual Setup

Section titled “Manual Setup”

The command line path above is two docker commands under the hood. To do it by hand:

Standalone binary (Linux)

Section titled “Standalone binary (Linux)”
Terminal window
# Download the latest standalone binary (server + embedded web UI)
wget https://vski.sh/x/platform/releases/download/latest/vski-standalone
chmod +x vski-standalone
sudo mv vski-standalone /usr/local/bin/vski


vski                   # serves on :3000, data in ./data

Docker

Section titled “Docker”
Terminal window
docker pull vski.sh/x/vski:latest-standalone


docker run -p 3000:3000 \
  -v "$(pwd)/data:/app/data" \
  -e JWT_SECRET=change-me \
  vski.sh/x/vski:latest-standalone

The light image (vski.sh/x/vski:latest) ships the API only, without the web UI.

First admin without the browser

Section titled “First admin without the browser”

The installer page just calls this API:

Terminal window
curl -X POST http://127.0.0.1:3000/api/admins/init \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@yourdomain.com", "password": "your-password"}'

The response contains the admin JWT.

Where next

Section titled “Where next”