4 Getting Started
Anton Nesterov edited this page 2026-11-01 20:55:38 +01:00

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

1. Install the command line tool

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:

vski doctor

2. Start a local server

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

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:

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:

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

4. Set up a project and apply it

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

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

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

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

Standalone binary (Linux)

# 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

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

The installer page just calls this API:

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