Hosting and backup

Running a server gets grixeld up on your machine. This page is for running it as something your team depends on: keeping it up, securing it for access beyond your own computer, backing it up, and keeping it healthy.

#Keep it running in the background

grixeld serve runs in the foreground and stops when you close the terminal. For a real deployment, run it under whatever keeps services alive on your host — systemd on Linux, launchd on macOS, or a process manager — so it restarts on crash and on reboot. A minimal systemd unit looks like:

[Unit]
Description=Grixel server
After=network.target

[Service]
ExecStart=/usr/local/bin/grixeld serve -data-root /srv/grixel-data -grpc-addr 0.0.0.0:8090
Restart=on-failure
User=grixel

[Install]
WantedBy=multi-user.target

Point -data-root at durable storage, and run the service as a dedicated user that owns that folder.

#Let other machines connect

By default the server listens on localhost, reachable only from the same machine. To let teammates connect, bind a reachable address (-grpc-addr 0.0.0.0:8090) and make sure your firewall allows it.

Once you're exposing the server beyond your own machine, turn on encryption. Give grixeld a TLS certificate and key:

grixeld serve -data-root /srv/grixel-data \
  -grpc-addr 0.0.0.0:8090 \
  -tls-cert /etc/grixel/cert.pem -tls-key /etc/grixel/key.pem

Clients then connect with grpcs:// instead of grpc://:

grixel login -server grpcs://your-server-host:8090 -token <token>

#Back it up

Everything is in the data root, so backing up the server means backing up that folder — but do it with the built-in command so you get a consistent snapshot. Backup is an offline command, so stop the server, back up, then start it again:

# stop grixeld first
grixeld backup -data-root /srv/grixel-data -out /backups/grixel-$(date +%F).tar.gz
# start grixeld again

Restore into a fresh (or replacement) data root:

grixeld restore -in /backups/grixel-2026-07-16.tar.gz -data-root /srv/grixel-data-restored

Keep backups off the server's own disk, and test a restore occasionally — an untested backup isn't a backup. The stored data is content-addressed, so successive backups mostly repeat unchanged data; ordinary incremental backup tools handle the archive folder well.

#Keep it healthy

A few offline maintenance commands (stop the server first for each):

grixeld verify  -data-root /srv/grixel-data     # integrity-check stored data, history, and the log
grixeld gc      -data-root /srv/grixel-data     # reclaim space from unreferenced data
grixeld info    -data-root /srv/grixel-data     # a summary of the data root's state

Run verify after any unclean shutdown or storage scare — it confirms the stored data is intact. Run gc periodically to reclaim space (use -dry-run first to see what it would remove).

#Watch it

grixeld exposes metrics for monitoring at -metrics-addr (default localhost:9090, path /metrics) in a format standard monitoring tools scrape. Point your monitoring at it to track health and load.

#Update the server

Updating is the same as installing — re-run the installer to get the new grixeld, then restart the service. Take a backup first. Clients and servers on nearby versions work together, so you don't have to update everyone at once.

#Scaling reads later

If many people on the same network read large files from one server, you can put a read-through cache in front of it so those reads are served locally instead of all hitting the main server. That's an optional add-on for later; a single server serves a team well to begin with.