ZDB — Documentation

1. install

one command. detects your OS, installs Node 20+, Kubo IPFS, PM2, and the ZDB server.

curl -fsSL https://zdb.zexvro.in/install.sh | bash

works on Linux, macOS, and Termux (Android). idempotent — safe to re-run for updates.

what it installs

Node.js 20+ (if missing)
Kubo IPFS 0.43+ (if missing)
PM2 process manager (if missing)
ZDB server source to ~/zdb
zdb CLI to ~/.local/bin/

2. cli commands

command	description
`zdb up`	start IPFS + ZDB daemons
`zdb up --info`	start and show system info
`zdb down`	stop all services
`zdb status`	check daemon status
`zdb info`	traffic, storage, memory, peers
`zdb logs`	tail daemon logs
`zdb install`	install or update ZDB

3. api

ZDB runs on http://localhost:8899 by default. all endpoints return JSON.

health

GET /health
// response
{
  "status": "ok",
  "version": "0.2.1",
  "uptime": 12345
}

create record

POST /v1/db/{collection}
Content-Type: application/json

{
  "name": "zexvro",
  "value": 42
}
// response
{
  "ok": true,
  "id": "a1b2c3d4e5f6",
  "cid": "Qm..."
}

get record

GET /v1/db/{collection}/{id}

// response: the stored JSON object

list records

GET /v1/db/{collection}

// response
{
  "records": [...],
  "total": 100,
  "page": 1
}

update record

PUT /v1/db/{collection}/{id}
Content-Type: application/json

{
  "name": "zexvro",
  "value": 99
}

delete record

DELETE /v1/db/{collection}/{id}

{
  "ok": true,
  "deleted": "a1b2c3d4e5f6"
}

query records

POST /v1/db/{collection}/query
Content-Type: application/json

{
  "where": {
    "field": "status",
    "op": "==",
    "value": "active"
  }
}

4. encryption

all data is AES-256-GCM encrypted before uploading to IPFS. encryption is on by default.

auto-generated key stored in data/settings.json as encryptKey
each shard gets a unique IV per encryption
backward-compatible: reads both encrypted and unencrypted shards
disable with ZDB_ENCRYPT=0 environment variable

5. ipfs integration

ZDB uses IPFS as its storage and verification layer.

every write uploads a new shard to IPFS and pins it
data is content-addressed — tamper-proof by design
CID explorer validates prefixes: Qm, bafy, bafk, zdb1
connect to remote IPFS nodes via IPFS_API_URL env var

environment variables

variable	default	description
`PORT`	8899	server port
`IPFS_API_URL`	http://localhost:5001	Kubo API endpoint
`ZDB_ENCRYPT`	1	enable AES-256-GCM encryption
`ZDB_IPFS_ONLY`	0	read data exclusively from IPFS
`ADMIN_KEY`	—	admin API authentication key

6. architecture

ZDB is designed as a lean, self-contained daemon. phone = storage/compute/IPFS. laptop = frontend/API.

server.mjs — entry point, HTTP server, route registration
engine.mjs — storage engine, CID shard chain, record CRUD
router.mjs — lightweight HTTP router + middleware pipeline
auth.mjs — scrypt auth, admin sessions, API key auth
security.mjs — rate limiter, CORS, CSP
logger.mjs — request logging ring buffer
ipfs.mjs — Kubo RPC client with encrypt/decrypt
crypto.mjs — AES-256-GCM encryption module
settings.mjs — settings persistence
admin.mjs — monitoring panel API routes
explorer.mjs — CID explorer with validation
rules.mjs — Firebase-style rules parser

zero npm dependencies. entire server fits in a single directory.

7. security

rate limiting on all endpoints
CORS with configurable origins
Content Security Policy headers
API key authentication for admin routes
scrypt password hashing
admin session management

8. termux (android)

ZDB runs natively on Android via Termux. no root required.

install: pkg install nodejs then run the installer
Kubo IPFS works in Termux — API on port 5001, swarm on 4001
auto-start on boot via Termux:Boot plugin
PM2 manages the ZDB process

tip: use Tailscale to connect your phone and laptop. the phone becomes your IPFS node and ZDB server, accessible from anywhere.

9. faq

what is ZDB?

ZDB is a web3-native database. it stores data on IPFS with end-to-end encryption. self-hosted, zero dependencies, runs anywhere Node.js runs.

why IPFS?

content-addressed storage means your data is tamper-proof by design. every write gets a CID — a cryptographic fingerprint of the data. no central authority, no vendor lock-in.

is it really zero dependencies?

yes. the server uses only Node.js built-ins. no npm install needed for the server itself.

can i use it in production?

ZDB is designed for self-hosted, personal, and small-team use. for high-traffic production, consider running multiple IPFS nodes for redundancy.