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:
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o kolo-pin ./cmd/kolo-pin$env:CGO_ENABLED="0"; $env:GOOS="linux"; $env:GOARCH="amd64"
go build -trimpath -o kolo-pin ./cmd/kolo-pinCGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o kolo-pin ./cmd/kolo-pinGo 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:
scp kolo-pin user@203.0.113.10:Then, on the server, put it where systemd can run it:
sudo install -m 0755 kolo-pin /usr/local/bin/kolo-pin3Create a user and a data folder
On the server, make an unprivileged user and a private data folder for it:
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-pinThe 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:
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pinIt prints the public key in hex. Yours will differ:
d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a5Try 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:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pinIt prints three lines and keeps running:
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=100000000000In a second SSH session on the server, ask the health endpoint:
curl http://127.0.0.1:7451/healthzokThe 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:
| Flag | Environment | Default | Meaning |
|---|---|---|---|
-data | KOLO_PIN_DATA | required | data folder: identity.key and the store |
-listen | KOLO_PIN_LISTEN | 127.0.0.1:7450 | UDP address for kolo-secure connections, IPv4 |
-max-bytes | KOLO_PIN_MAX_BYTES | 100GB | most bytes stored for all owners together; B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
-owners | KOLO_PIN_OWNERS | empty | comma-separated hex owner keys to accept; empty accepts any owner and logs a warning at start |
-max-owners | KOLO_PIN_MAX_OWNERS | 100000 | most owner records kept, one per owner key ever seen; a new owner past it is refused (ErrOwnerLimit) |
-max-conns | KOLO_PIN_MAX_CONNS | 100 | most connections at once, handshaking or open; from 1 to 10000 |
-max-conns-per-ip | KOLO_PIN_MAX_CONNS_PER_IP | 4 | most connections from one source address, at most -max-conns; raise it for owners behind one NAT |
-add-timeout | KOLO_PIN_ADD_TIMEOUT | none | most time one add may spend, such as 10m; past it the add is refused as busy and what was stored is kept |
-health | KOLO_PIN_HEALTH | 127.0.0.1:7451 | TCP address of GET /healthz, or off |
-metrics | KOLO_PIN_METRICS | 127.0.0.1:7452 | TCP address of GET /metrics, or off |
-log-format | KOLO_PIN_LOG_FORMAT | text | text or json, on stderr |
-log-level | KOLO_PIN_LOG_LEVEL | info | debug, 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:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 0.0.0.0:7450Or on the server's public address only:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 203.0.113.10:7450Kolo is IPv4 only. An IPv6 address, v4-mapped included, is refused:
kolo-pin: address "[::1]:7450": IPv6 is not supported, use IPv4A 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:
sudo ufw allow 7450/udpWith firewalld:
sudo firewall-cmd --permanent --add-port=7450/udp
sudo firewall-cmd --reloadLeave 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:
[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.targetRestartPreventExitStatus=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:
sudo systemctl daemon-reload
sudo systemctl enable --now kolo-pin
journalctl -u kolo-pin -fYou 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:
curl http://127.0.0.1:7451/healthzokFrom your computer, reach it through an SSH tunnel instead of opening the port:
ssh -L 7451:127.0.0.1:7451 user@203.0.113.10While the tunnel is open, ask it from a second terminal on your computer:
curl http://127.0.0.1:7451/healthzcurl.exe http://127.0.0.1:7451/healthzcurl http://127.0.0.1:7451/healthzIt 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:
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pinThe 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.
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:
go run . d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a 203.0.113.10:7450It prints the owner's key, then what the pinning peer holds. Your keys and log ID will differ:
owner a8ad43ab31caffbc78a3ea089e39e493a0f0c82da7e8cfeb58c16a5cd7245380
pinned log 9b42c4ca: 4 entries, 2896 of 100000000 bytes used
status: 4 entries, kept until 2026-12-12And the pinning peer logs the request:
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=2896This 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,Addreturnspin: owner quota exceeded(ErrQuotaExceeded). - The peer's total for all owners (
-max-bytes, 100GB by default). Past it,Addreturnspin: 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
- Read the kolo-pin page: its API, its limits and its errors.
- Watch it with Prometheus: Monitoring a pinning peer.
- Keep each log on more than one pinning peer: Choosing pinning peers.
- See Replicas for how a copy of a log is checked.