# Configure a node

**Applies to:** development build 0.1.1. Basic networking and storage flags also exist in the public baseline; capacity protection and newer recovery controls require the development build. Check `smkv-server --help` on the actual binary.

## Configuration entry points

For packaged services, edit `/etc/default/smkv` and restart deliberately. `SMKV_ARGS` is an argument list interpreted by systemd, with no shell substitution. For a foreground process, pass the same flags to `smkv-server`. Sharded nodes also read a JSON cluster map; security uses a separate optional JSON file.

```sh
SMKV_ARGS="--bind 127.0.0.1:7379 --metrics-bind 127.0.0.1:9108 --partitions 16 --workers 4 --max-entries 100000 --max-log-bytes 1073741824"
```

This example is an environment-file line, not a command that starts the server. It preserves small evaluation limits, not production sizing.

## Core settings

| Flag | Default | Meaning |
| --- | --- | --- |
| `--partitions` | 16 | Fixed logical partitions; cannot change when reopening data |
| `--workers` | 4 | Dedicated storage threads; may change across restarts |
| `--queue-capacity` | 64 | Bounded requests per storage worker |
| `--max-connections` | 128 | Concurrent TCP connection bound |
| `--max-entries` | 100000 | Node indexed-entry budget, split across partitions |
| `--max-log-bytes` | 1073741824 | Node retained-log budget, split across partitions |
| `--segment-bytes` | 67108864 | Segment rotation target; a larger record can occupy its own segment |
| `--expiry-interval-ms` | 100 | Paced expiration maintenance; 0 disables it |
| `--metrics-bind` | Disabled unless supplied | Private HTTP Prometheus listener |

Default maximum key size is 1 KiB and value size is 1 MiB. Size your workload within the configured limits, including table/key and row-encoding overhead. Choose workers no greater than the partition count.

## Plan per-node capacity

Entry/log budgets are node totals, not per-partition settings. RF2 stores two copies across the cluster. Count owned primary and replica entries when sizing each node. Unused quota in one partition is not freely shared with another. Maps can declare different node budgets; each partition uses the smaller quota supported by its two owners.

Retained logs include old values and deletes, not just live payload bytes. Checkpoints, incoming replicas, and ownership transfers require temporary disk and memory headroom. An index estimate is not RSS; include allocator, history, networking, and copy overhead. RAM of 32–128 GB does not imply a fixed safe record count. Measure with representative keys and payloads.

## Preserve headroom

Linux development servers sample physical disk, inodes, process RSS, available host memory, and applicable cgroup-v2 memory limits. Normal puts preserve a floor plus a maintenance reserve; maintenance can use the reserve but must preserve the floor.

| Flag | Default bytes |
| --- | ---: |
| `--capacity-disk-floor-bytes` | 67108864 |
| `--capacity-disk-reserve-bytes` | 1073741824 |
| `--capacity-memory-floor-bytes` | 268435456 |
| `--capacity-memory-reserve-bytes` | 536870912 |
| `--capacity-resume-margin-bytes` | 134217728 |
| `--capacity-max-rss-bytes` | 0 (additional RSS ceiling disabled) |

`--maintenance-log-percent` reserves 5% of logical log quota by default. These are available-byte thresholds, not used-space percentages. There is no automatic eviction. Larger copies may require substantially more headroom than these defaults.

```sh
smkv-ctl --seed 10.0.0.11:7381 capacity --json
```

States are `normal`, `pressure`, and `writes_blocked`. Reads remain routable under capacity pressure. Missing or stale resource samples reject mutations. Non-Linux servers default to disabled physical sampling; startup index reconstruction is not memory-bounded by the governor.

## Apply changes deliberately

Record the existing arguments, stop the affected service, edit configuration, and restart. Check logs, readiness, replica progress, and capacity before moving to another node. Do not lower logical quotas below stored data. Do not delete manifests, locks, segments, or identity files to make a new configuration start.