VoidDB

Features

AI Agent Guide

Every running VoidDB server exposes a machine-readable markdown guide for AI agents and automation tools.

# Fetch the live server guide
curl http://localhost:7700/skill.md

# Alternate well-known path
curl http://localhost:7700/.well-known/voiddb-skill.md

The repository copy lives here: SKILL.md.

Quick Start

# Clone and run the interactive setup wizard
git clone https://github.com/Nopass0/void.git
cd void
.\scripts\setup.ps1

# Or start directly (builds automatically)
.\scripts\run.ps1

# With admin panel
.\scripts\run.ps1 -WithAdmin

git clone https://github.com/Nopass0/void.git && cd void
chmod +x scripts/*.sh
./scripts/setup.sh           # interactive wizard

# Or start directly
./scripts/run.sh
./scripts/run.sh --with-admin  # server + admin panel

git clone https://github.com/Nopass0/void.git && cd void
cp .env.example .env          # edit JWT_SECRET + ADMIN_PASSWORD
docker compose up -d

# API at http://localhost:7700
# Admin at http://localhost:3000

First steps

# Log in with CLI
voidcli login              # default: admin / admin

# Create a database and collection
voidcli db  create myapp
voidcli col create myapp users

# Insert a document
voidcli doc insert myapp users '{"name":"Alice","age":30,"active":true}'

# Query documents
voidcli doc find myapp users '{"where":[{"field":"age","op":"gt","value":18}]}'

# Backup
voidcli backup

REST API

Base URL: http://localhost:7700  |  All endpoints return JSON  |  Auth via Authorization: Bearer <token>

Authentication

Databases & Collections

Documents

Query syntax

// POST /v1/databases/myapp/users/query
{
  "where": {
    "AND": [
      { "field": "age",    "op": "gte",        "value": 18 },
      { "field": "active", "op": "eq",         "value": true },
      { "field": "name",   "op": "starts_with", "value": "A" }
    ]
  },
  "order_by": [{ "field": "age", "dir": "asc" }],
  "limit": 25,
  "skip":  0
}

Supported operators: eq ne gt gte lt lte contains starts_with in

S3-Compatible Blob API

Blob Fields In Documents

{
  "_blob_bucket": "media",
  "_blob_key": "assets/123/original/photo.jpg",
  "_blob_url": "https://db.example.com/s3/media/assets/123/original/photo.jpg"
}

Backup API

Cache API

CLI — voidcli

Build with go build ./cmd/voidcli or run .\scripts\setup.ps1 which adds it to your PATH automatically.

voidcli [--url http://host:7700] [--token JWT] COMMAND

# Authentication
voidcli login [--user admin]
voidcli logout
voidcli status

# Database management
voidcli db list
voidcli db create <name>
voidcli db drop   <name>

# Collection management
voidcli col list   <db>
voidcli col create <db> <name>
voidcli col drop   <db> <name>

# Document operations
voidcli doc insert <db> <col> '{"field":"value"}'
voidcli doc insert <db> <col> @myfile.json   # from file
voidcli doc find   <db> <col> [filter-json]
voidcli doc get    <db> <col> <id>
voidcli doc delete <db> <col> <id>

# Backup
voidcli backup              # all databases
voidcli backup mydb         # specific database
voidcli restore backup.void

ORM Libraries

import { VoidClient, query } from '@voiddb/orm';

const client = new VoidClient({ url: 'http://localhost:7700' });
await client.login('admin', 'admin');

const users = client.db('myapp').collection<User>('users');

// Insert
const id = await users.insert({ name: 'Alice', age: 30, active: true });

// Get by ID
const user = await users.get(id);

// Query (builder passed into find)
const results = await users.find(
  query()
    .where('age', 'gte', 18)
    .where('active', 'eq', true)
    .orderBy('age', 'asc')
    .limit(10)
);

// Update
await users.patch(id, { age: 31 });

// Cache
await client.cache.set('session:alice', { loggedIn: true }, 3600);

// Delete
await users.delete(id);

import voidorm "github.com/voiddb/void/orm/go"

client, _ := voidorm.New(voidorm.Config{
    URL:      "http://localhost:7700",
    Username: "admin",
    Password: "admin",
})

col := client.DB("myapp").Collection("users")

// Insert
id, _ := col.Insert(voidorm.Doc{
    "name": "Alice", "age": 30,
})

// Query
res, _ := col.Query().
    Where("age", voidorm.Gte, 18).
    OrderBy("age", voidorm.Asc).
    Limit(10).
    Execute()

// Get / Delete
doc, _ := col.GetByID(id)
col.Delete(id)

Configuration

Edit config.yaml or set VOID_* environment variables (env vars take precedence).