SparkD

SparkD is a cell engine for databases. Run it on your laptop, home server, or VPS, then create isolated PostgreSQL cells over a normal TCP API.

PostgreSQL support is first. SparkD imports PostgreSQL into the base rootfs once, then clones that imported base for each cell.

What You Get

• TCP HTTP API on port 8721 by default
• /create, /list, /pause, /resume, /monitor, /delete, /health
• JSON responses for every daemon endpoint
• PostgreSQL credentials and connection strings from /create
• Per-cell rootfs, PID/network namespace, IP, and forwarded host port
• JSON metadata in /var/lib/sparkd/cells.json
• RAM/CPU enforcement with cgroup v2
• Disk enforcement with a quota-sized ext4 rootfs image per cell

Build

go build -o sparkd .

SparkD needs root for chroot, namespaces, veth devices, bridge setup, cgroups, loop-mounted rootfs images, and iptables.

Build on a VPS:

ssh user@server-ip
git clone https://github.com/shellhaki/sparkd.git
cd sparkd
go build -o sparkd .
sudo ./sparkd daemon

One-command systemd install on a VPS:

curl -fsSL https://raw.githubusercontent.com/shellhaki/sparkd/main/scripts/install-systemd.sh | sudo sh

The installer clones https://github.com/shellhaki/sparkd.git, builds SparkD, starts sparkd.service, and prints the useful systemctl and journalctl commands.

Run

sudo ./sparkd daemon

Default server:

0.0.0.0:8721

Use a different address or port if 8721 is busy:

sudo SPARKD_ADDR=0.0.0.0:8877 ./sparkd daemon

Set SPARKD_HOST if returned database connection strings should use a specific public IP or DNS name:

sudo SPARKD_HOST=db.example.com ./sparkd daemon

Open the daemon port on your VPS firewall/security group. For quick local-only testing, run with SPARKD_ADDR=127.0.0.1:8721.

systemd

Use the installer:

sudo sh scripts/install-systemd.sh

Example unit:

[Unit]
Description=SparkD database cell daemon
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/sparkd daemon
Environment=SPARKD_ADDR=0.0.0.0:8721
Environment=SPARKD_HOST=server-ip-or-dns
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target

Install:

sudo cp sparkd /usr/local/bin/sparkd
sudo cp sparkd.service /etc/systemd/system/sparkd.service
sudo systemctl daemon-reload
sudo systemctl enable --now sparkd

API

Base URL:

http://server-ip:8721

Health:

curl http://127.0.0.1:8721/health

Create a Postgres cell:

curl -X POST http://127.0.0.1:8721/create \
  -H 'content-type: application/json' \
  -d '{"name":"app-db","dbtype":"pg","port":3001,"ram":"128mb","disk":"512mb"}'

Response includes cell metadata, progress events, credentials, and the connection string:

{
  "connection_string": "postgres://postgres:...@server-ip:3001/app_db?sslmode=disable"
}

List cells:

curl http://127.0.0.1:8721/list

Monitor one cell:

curl 'http://127.0.0.1:8721/monitor?name=app-db'

Pause one cell:

curl -X POST http://127.0.0.1:8721/pause \
  -H 'content-type: application/json' \
  -d '{"name":"app-db"}'

Resume one cell:

curl -X POST http://127.0.0.1:8721/resume \
  -H 'content-type: application/json' \
  -d '{"name":"app-db"}'

Delete one cell:

curl -X POST http://127.0.0.1:8721/delete \
  -H 'content-type: application/json' \
  -d '{"name":"app-db"}'

Import PostgreSQL Once

The daemon imports automatically on first /create, but you can warm it manually:

sudo ./sparkd import

Manual Tests

sudo ./main daemon
./manual-tests/create-pg.sh
./manual-tests/list.sh
./manual-tests/delete-pg.sh

For a remote daemon:

SPARKD_URL=http://server-ip:8721 ./manual-tests/list.sh

Code Examples

Client examples live in examples:

• Go
• Rust
• TypeScript
• Zig
• Odin

State

Defaults:

• State directory: /var/lib/sparkd
• Base rootfs: /var/lib/sparkd/base/rootfs
• Cell directory: /var/lib/sparkd/cells
• Metadata store: /var/lib/sparkd/cells.json

Override state for local experiments:

sudo SPARKD_STATE_DIR=/tmp/sparkd-state SPARKD_ADDR=127.0.0.1:8721 ./sparkd daemon