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
- Collections and Records: fields, types, filters, relations
- Rules and Access Control: who can read and write what
- Workflows and Pipelines: durable automation
- Command Line and Infrastructure as Code: the full command reference and the declarative format
- Realtime, Graphs, Vector Embeddings, Plugins
- Introduction
- Performance
- Getting Started
- Coding Agents
- Command Line
- Infra as Code
- CI/CD Guide
- Project Boilerplate
- SDKs
- Authentication
- Databases
- Collections
- Gated Queries
- Graphs
- Rules and Access Control
- Granular Access Control
- Triggers
- Plugins
- Containers Plugin
- vski mcp
- Realtime
- Full Text Search
- Vector Embeddings
- KWH
- Workflows
- Pipelines
- Dashboard Widgets
- Connectors
- Cron
- Webhooks
- Gates
- Migrations
- Replication
- File Sync
- Backup
- Distributed Realtime
- Tutorial: ReactJS Todo
- Tutorial: Graph-Memory Agent
- Tutorial: Image Gallery
- Tutorial: Embeddings
- Tutorial: Graphs
- Recipe: Calendar Timetree
- Tutorial: Plugins
- Tutorial: MCP Server