kolo docsbeta

Run a pinning peer on a VPS

A step-by-step guide. Build the kolo-pin binary, run it on a Linux server with systemd, and pin a log to it from an owner's computer.

On this page

A pinning peer keeps your logs available while your own devices are offline. It stores the ciphertext and never gets the keys to read it. This guide builds the kolo-pin command, runs it on a Linux VPS and pins a log to it from an owner's computer. See kolo-pin for the library.

The guide uses 203.0.113.10 as the VPS's public IPv4 address. Use your own server's address instead.

1Build the binary

On your computer, in the kolo-pin source folder, build a static Linux binary:

bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o kolo-pin ./cmd/kolo-pin

Go prints nothing and leaves a file named kolo-pin. It needs no other files on the server.

2Copy it to the VPS

Copy the binary to your server:

Terminal
scp kolo-pin user@203.0.113.10:

Then, on the server, put it where systemd can run it:

bash
sudo install -m 0755 kolo-pin /usr/local/bin/kolo-pin

3Create a user and a data folder

On the server, make an unprivileged user and a private data folder for it:

bash
sudo useradd --system --home-dir /var/lib/kolo-pin --shell /usr/sbin/nologin kolo-pin
sudo install -d -m 0700 -o kolo-pin -g kolo-pin /var/lib/kolo-pin

The folder must be private (mode 0700). kolo-pin refuses one that others can access, and keeps its key (identity.key, mode 0600) and its store (store/) in it.

4Print the pinning peer's key

Owners put this key in their capabilities. The first run creates it, and it stays the same across restarts:

bash
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pin

It prints the public key in hex. Yours will differ:

Text
d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a

5Try it on loopback first

With only -data, kolo-pin listens on 127.0.0.1:7450 and nobody outside the server can reach it. Start it in the foreground:

bash
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin

It prints three lines and keeps running:

Text
time=2026-11-12T08:16:33.990+07:00 level=INFO msg=health addr=127.0.0.1:7451
time=2026-11-12T08:16:33.990+07:00 level=INFO msg=metrics addr=127.0.0.1:7452
time=2026-11-12T08:16:34.041+07:00 level=INFO msg=serving key=d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a addr=127.0.0.1:7450 owners=0 used=0 max-bytes=100000000000

In a second SSH session on the server, ask the health endpoint:

bash
curl http://127.0.0.1:7451/healthz
Text
ok

The metrics line is the Prometheus endpoint, GET /metrics on 127.0.0.1:7452. Monitoring a pinning peer covers it.

Press Ctrl-C in the first session. kolo-pin closes its store, prints msg=stopped and exits with code 0.

6Choose the flags

Each flag has an environment variable, and a flag wins over its variable:

FlagEnvironmentDefaultMeaning
-dataKOLO_PIN_DATArequireddata folder: identity.key and the store
-listenKOLO_PIN_LISTEN127.0.0.1:7450UDP address for kolo-secure connections, IPv4
-max-bytesKOLO_PIN_MAX_BYTES100GBmost bytes stored for all owners together; B, KB, MB, GB, TB, KiB, MiB, GiB, TiB
-ownersKOLO_PIN_OWNERSemptycomma-separated hex owner keys to accept; empty accepts any owner and logs a warning at start
-max-ownersKOLO_PIN_MAX_OWNERS100000most owner records kept, one per owner key ever seen; a new owner past it is refused (ErrOwnerLimit)
-max-connsKOLO_PIN_MAX_CONNS100most connections at once, handshaking or open; from 1 to 10000
-max-conns-per-ipKOLO_PIN_MAX_CONNS_PER_IP4most connections from one source address, at most -max-conns; raise it for owners behind one NAT
-add-timeoutKOLO_PIN_ADD_TIMEOUTnonemost time one add may spend, such as 10m; past it the add is refused as busy and what was stored is kept
-healthKOLO_PIN_HEALTH127.0.0.1:7451TCP address of GET /healthz, or off
-metricsKOLO_PIN_METRICS127.0.0.1:7452TCP address of GET /metrics, or off
-log-formatKOLO_PIN_LOG_FORMATtexttext or json, on stderr
-log-levelKOLO_PIN_LOG_LEVELinfodebug, info, warn or error

Choose -max-bytes for the server's RAM as well as its disk. An open log keeps about 250 bytes of memory per entry and reads the ciphertexts from disk, and kolo-pin keeps up to 64 logs open. That cap counts logs, not entries, so in the worst case, 64 open logs that fill -max-bytes with the smallest entries take about 0.42 times -max-bytes in memory: about 40 GB for the default 100GB. Any peer that knows their owner keys and log IDs can make kolo-pin open them.

To let owners reach it, listen on every IPv4 address of the server:

bash
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 0.0.0.0:7450

Or on the server's public address only:

bash
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 203.0.113.10:7450

Kolo is IPv4 only. An IPv6 address, v4-mapped included, is refused:

Text
kolo-pin: address "[::1]:7450": IPv6 is not supported, use IPv4

A bad flag exits with code 2, including an invalid -listen, -health or -metrics address. A failure to start, such as a port already in use, exits with code 1. If you take an owner off -owners, kolo-pin deletes that owner's logs at the next start and logs dropped with the reason owner not accepted.

7Open UDP port 7450

kolo-secure runs over QUIC, which is UDP, so TCP rules do not help. Open UDP port 7450 for IPv4 in the server's firewall, and in your provider's firewall if it has one. With ufw:

bash
sudo ufw allow 7450/udp

With firewalld:

bash
sudo firewall-cmd --permanent --add-port=7450/udp
sudo firewall-cmd --reload

Leave the health port 7451 and the metrics port 7452 closed. Both answer on 127.0.0.1 only and should stay private.

8Run it with systemd

Create /etc/systemd/system/kolo-pin.service on the server. The settings go in environment variables:

/etc/systemd/system/kolo-pin.service
[Unit]
Description=kolo-pin pinning peer
After=network-online.target
Wants=network-online.target

[Service]
Type=exec
ExecStart=/usr/local/bin/kolo-pin run
Environment=KOLO_PIN_DATA=/var/lib/kolo-pin
Environment=KOLO_PIN_LISTEN=0.0.0.0:7450
Environment=KOLO_PIN_MAX_BYTES=100GB
Environment=KOLO_PIN_METRICS=127.0.0.1:7452
Restart=on-failure
RestartSec=5s
RestartPreventExitStatus=2
User=kolo-pin
Group=kolo-pin
UMask=0077
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/kolo-pin
RestrictAddressFamilies=AF_INET AF_UNIX

[Install]
WantedBy=multi-user.target

RestartPreventExitStatus=2 keeps systemd from restarting it after a bad flag. Add Environment=KOLO_PIN_OWNERS=... with your owners' keys to keep the peer for them. Then start it and follow its logs:

bash
sudo systemctl daemon-reload
sudo systemctl enable --now kolo-pin
journalctl -u kolo-pin -f

You should see the health, metrics and serving lines from step 5, with addr set to the address you listen on. systemctl stop kolo-pin sends SIGTERM, and kolo-pin stops cleanly.

9Check its health

On the server:

bash
curl http://127.0.0.1:7451/healthz
Text
ok

From your computer, reach it through an SSH tunnel instead of opening the port:

Terminal
ssh -L 7451:127.0.0.1:7451 user@203.0.113.10

While the tunnel is open, ask it from a second terminal on your computer:

bash
curl http://127.0.0.1:7451/healthz

It answers ok with status 200 while the peer runs.

The metrics endpoint on port 7452 works the same way, through ssh -L 7452:127.0.0.1:7452. Keep it local too, and see Monitoring a pinning peer to scrape it with Prometheus and set alerts.

10Give owners the key and the address

An owner needs two things. The first is the key from step 4:

bash
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pin

The second is the address: the server's public IPv4 address and the UDP port you listen on, here 203.0.113.10:7450. Send both to the owner in a way you trust, since an owner who gets a wrong key cannot reach the peer.

11Pin a log from an owner's computer

On the owner's computer, in a Go module that requires kolo-pin, kolo-id and kolo-store, this program writes a small log, signs a capability for the pinning peer and adds the log to it. It takes the pinning peer's key and address as arguments.

main.go
package main

import (
	"context"
	"crypto/ed25519"
	"encoding/hex"
	"fmt"
	"log"
	"os"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	"github.com/ciranda-dev/kolo-pin"
	kolostore "github.com/ciranda-dev/kolo-store"
)

func main() {
	if len(os.Args) != 3 {
		log.Fatal("usage: owner PEER-KEY IP:PORT")
	}
	key, err := hex.DecodeString(os.Args[1])
	if err != nil || len(key) != ed25519.PublicKeySize {
		log.Fatal("PEER-KEY must be 64 hex digits")
	}
	peer := pin.Peer{ID: key, Addr: os.Args[2]}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	owner, err := koloid.Generate() // in memory only, a new owner each run
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("owner %x\n", owner.PublicKey())
	st := kolostore.New(kolostore.NewMemory())
	defer st.Close()
	l, err := st.Create(owner)
	if err != nil {
		log.Fatal(err)
	}
	for _, v := range []string{"hello", "from", "my", "laptop"} {
		if _, err := l.Append([]byte(v)); err != nil {
			log.Fatal(err)
		}
	}

	capability, err := pin.Issue(owner, pin.Capability{
		Peer:    peer.ID,
		Expires: time.Now().Add(30 * 24 * time.Hour),
		Quota:   100_000_000,
	})
	if err != nil {
		log.Fatal(err)
	}
	info, err := pin.Add(ctx, owner, peer, l, capability)
	if err != nil {
		log.Fatal(err)
	}
	logID := l.ID()
	fmt.Printf("pinned log %x: %d entries, %d of %d bytes used\n", logID[:4], info.Entries, info.Used, info.Quota)

	info, err = pin.Status(ctx, owner, peer, logID)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("status: %d entries, kept until %s\n", info.Entries, info.Expires.Format(time.DateOnly))
}

Run it with the key and address of your pinning peer:

Terminal
go run . d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a 203.0.113.10:7450

It prints the owner's key, then what the pinning peer holds. Your keys and log ID will differ:

Text
owner a8ad43ab31caffbc78a3ea089e39e493a0f0c82da7e8cfeb58c16a5cd7245380
pinned log 9b42c4ca: 4 entries, 2896 of 100000000 bytes used
status: 4 entries, kept until 2026-12-12

And the pinning peer logs the request:

Text
time=2026-11-12T08:16:36.111+07:00 level=INFO msg=pinned op=add peer=a8ad43ab31caffbc78a3ea089e39e493a0f0c82da7e8cfeb58c16a5cd7245380 addr=127.0.0.1:52160 log=9b42c4caad2d363f2ce04dc7e8934f05c4abb44be9ba8b029cd8e67358c5b8e1 entries=4 used=2896

This run was on loopback, so addr is 127.0.0.1; on a VPS it is the owner's IP address and port.

Call pin.Add again after new entries or deletes; that is how the pinning peer catches up. This sample makes a new owner key each run, so a peer with -owners set refuses it with pin: not authorized. A real application keeps its owner key with kolo-id, and the operator lists that key.

What the pinning peer sees

It sees which owner keys and log IDs it hosts, their entry counts and sizes, the signed records, when each log grows, is deleted from or is pulled, and for every request the requester's key, IP address and timing. Its logs show some of this, as in the pinned line above.

It never gets an entry key or any plaintext, so it cannot read the entries. Anyone who knows an owner key and log ID can pull the ciphertext and records from it, or fetch a range of entries with kolo-sync Fetch, and learn the same metadata. No answer from it carries a key.

Limits and their errors

Two limits, each with its own error, both checked before anything is stored:

  • The owner's quota from the capability (Quota, 0 for none). Past it, Add returns pin: owner quota exceeded (ErrQuotaExceeded).
  • The peer's total for all owners (-max-bytes, 100GB by default). Past it, Add returns pin: pinning peer disk full (ErrDiskFull).

Nothing is evicted to make room, and deletes always pass. Bytes are counted as stored keys and values, not disk blocks, so leave room on the disk above -max-bytes.

One entry must fit in one kolo-sync message of at most 4 MiB, with its record and encryption overhead, or Add returns pin: too large (ErrTooLarge). An entry of exactly 4 MiB is already too large, so split large files into several entries.

When a capability expires (checked every minute), or the owner sends a revoke note, the pinning peer deletes every log of that owner.

Deletion is best effort

The pinning peer applies an owner's new delete markers at the next Add, as kolo-sync hands them over, and drops their ciphertexts in the same write. A peer that does not follow the protocol keeps what it has, and old disk blocks can still hold deleted bytes. Since the pinning peer never had the entry keys, it could not read those entries anyway. See Deletion.

What was not tested

Every run behind this guide was on one computer, on 127.0.0.1: the build, kolo-pin id, kolo-pin run, the health and metrics endpoints and the owner program. A real VPS, real NAT, the systemd unit, the firewall commands and the Windows commands were not tested.

Next steps