Configuration

Amaquet configuration controls two listeners, authentication, optional persistence, memory governance, request admission, upload handling, and adaptive in-memory compression. The server reads JSON, applies supported environment overrides, validates the merged result, creates required runtime directories, and only then starts serving traffic.

The configuration reference is the exhaustive field-by-field reference. This page explains how to choose values for common deployments and what each group means operationally.

Configuration lifecycle

Amaquet applies configuration in this order:

1. Start with compiled defaults.
2. Read the JSON file named by -config, defaulting to ./amaquet.json. A missing file is allowed and leaves the defaults in place.
3. Apply supported AMAQUET_* environment variables. An environment value wins over the JSON value for the field it controls.
4. Validate ports, limits, enum values, TLS material, and listener security rules.
5. Create data_dir, load administration state, initialize persistence and compression, and start both listeners.

Invalid JSON or an invalid merged value stops startup. Invalid numeric environment strings are ignored by the loader and leave the earlier JSON/default value in place; the resulting configuration is still validated. Relative paths are resolved from the server process’s current working directory, so service managers should set a fixed working directory or use absolute paths.

Generate a complete starting file rather than hand-writing every default:

./bin/amaquet --init-config --config ./amaquet.json

This writes a random security.bootstrap_token, prints it once, and exits. It does not apply environment overrides. Keep the file private. During normal startup, an empty bootstrap value causes Amaquet to reuse or create data_dir/bootstrap-token with mode 0600 and log the protected path rather than the secret.

Local development profile

The generated configuration is a good local starting point because both listeners bind to loopback and native authentication is enabled. A minimal hand-written equivalent is:

{
  "protocol": {
    "host": "127.0.0.1",
    "port": 13378,
    "require_auth": true
  },
  "admin": {
    "host": "127.0.0.1",
    "port": 13379
  },
  "data_dir": "./data"
}

Omitted fields receive the defaults listed below. Use the token generated by --init-config, or the protected token file created on first start, for the first authenticated request. Do not set require_auth to false merely to avoid handling credentials unless the process is completely isolated and disposable.

Networked deployment profile

A networked deployment should use separate TLS policies for the data plane and control plane, private bind addresses, explicit persistent paths, and a memory budget below the host or container limit. The following is an illustrative shape; replace every certificate, key, token, and storage path with deployment-specific values:

{
  "protocol": {
    "host": "10.0.10.15",
    "port": 13378,
    "tls": true,
    "tls_cert_file": "/etc/amaquet/tls/protocol.crt",
    "tls_key_file": "/etc/amaquet/tls/protocol.key",
    "require_auth": true,
    "read_timeout_ms": 120000,
    "write_timeout_ms": 30000
  },
  "admin": {
    "host": "10.0.20.15",
    "port": 13379,
    "tls": true,
    "tls_cert_file": "/etc/amaquet/tls/admin.crt",
    "tls_key_file": "/etc/amaquet/tls/admin.key",
    "metrics_require_auth": true
  },
  "security": {
    "public_key_file": "/etc/amaquet/identity/public.pem",
    "private_key_file": "/etc/amaquet/identity/private.pem"
  },
  "persistence": {
    "aof_enabled": true,
    "aof_path": "/var/lib/amaquet/amaquet.aof",
    "fsync": "everysec"
  },
  "limits": {
    "max_connections": 2000,
    "max_memory_bytes": 6442450944,
    "eviction_policy": "noeviction",
    "max_inflight_requests": 4096,
    "max_inflight_per_connection": 128,
    "command_timeout_ms": 30000
  },
  "data_dir": "/var/lib/amaquet"
}

protocol.allow_insecure_auth and admin.allow_insecure remain false in this profile. They are validation escape hatches for deliberately isolated plaintext networks, not substitutes for TLS.

Protocol listener

The protocol object configures the binary Amaquet data-plane endpoint used by amaquet-cli and the Go client. Plaintext clients use amaquet://; TLS clients use amaquets://.

protocol.host and protocol.port

host is the local bind address and defaults to 127.0.0.1; port defaults to 13378 and must be between 1 and 65535. Loopback is appropriate for a local process. A wildcard address such as 0.0.0.0 exposes the service on every IPv4 interface and should be avoided unless firewalling and TLS are already designed.

protocol.tls, protocol.tls_cert_file, and protocol.tls_key_file

Set tls to true to encrypt native protocol connections. Both certificate and private-key paths are required, readable by the service account, and expected to match the hostnames used by clients. These files are for transport TLS; optional Ed25519 identity files are a separate application-level identity mechanism.

protocol.require_auth

The default is true. New native connections must authenticate with AUTH before protected commands are accepted. If false, new connections are anonymous administrative actors, which is suitable only for an isolated local test process. It is not a replacement for authorization in a shared environment.

protocol.allow_insecure_auth

This is false by default and does not disable authentication. It permits the specific combination of a non-loopback host, required authentication, and plaintext transport. Enable it only when another trusted network boundary provides the protection; TLS is the recommended solution.

protocol.read_timeout_ms and protocol.write_timeout_ms

The read timeout defaults to 120000 milliseconds and limits incomplete frames or idle input. The write timeout defaults to 30000 milliseconds and limits response or event writes to slow readers. 0 disables the respective deadline; use that only when connection lifetime is controlled elsewhere.

Administration listener

The admin object configures the HTTP control plane. It serves /api/* and /metrics, not a user interface. Keep it on loopback or a private management network whenever possible.

admin.host and admin.port

The defaults are 127.0.0.1 and 13379. The admin port is independent of the native protocol port. A non-loopback admin host must use HTTPS or explicitly set admin.allow_insecure.

admin.tls, admin.tls_cert_file, and admin.tls_key_file

Enable admin.tls for HTTPS and provide a certificate/key pair. Admin TLS has independent paths from protocol TLS so control-plane certificates can use a separate hostname, trust chain, and rotation schedule.

admin.allow_insecure

Allows plaintext HTTP on a non-loopback admin address. It is intended only for an isolated development network or a deployment where an explicitly trusted boundary provides the transport protection. It does not make the admin API unauthenticated.

admin.metrics_require_auth

The default is true, so /metrics requires an authenticated admin request. Set it to false only when the metrics listener is already isolated and exposing runtime information to the monitoring network is intentional.

admin.max_sessions

The default is 10000 server-side HTTP sessions. Sessions are independent of native protocol connections and API keys and normally expire after twelve hours. Lower this value on a constrained admin process; raise it only when the number of simultaneous browser/session clients justifies the memory use.

admin.auth_failures_per_minute

The default is 20 failed authentication attempts per source address per minute. It must be positive. This throttle helps slow credential guessing but should be combined with TLS, firewall restrictions, strong secrets, and monitoring.

Security and identity

These settings control the first administrative credential and the optional cryptographic identity that clients can verify after connecting.

security.bootstrap_token

This is the initial administrative credential. --init-config generates one. With an empty value, startup reads or creates data_dir/bootstrap-token; an environment value from AMAQUET_BOOTSTRAP_TOKEN takes precedence at runtime. Use the bootstrap credential to create a permanent API key, then remove it from routine application configuration. After the first admin API key is created, bootstrap authentication is permanently disabled in persisted admin state.

security.public_key_file and security.private_key_file

These paths enable the optional Ed25519 protocol identity. Generate matching files with amaquet-keygen, protect the private key, and configure both paths. Clients can verify the server identity fingerprint/signature after HELLO. This key pair does not replace X.509 certificates or provide encryption.

Persistence

Amaquet is still an in-memory database when AOF is enabled. AOF records committed mutations for restart recovery; it does not turn the engine into a disk-backed database or eliminate the need for backups.

persistence.aof_enabled

The default is false. With AOF disabled, a restart begins with an empty data keyspace, while control-plane state may remain in data_dir/admin.json. With AOF enabled, committed records are replayed before listeners accept traffic. Enable it when restart recovery is required and size storage for journal growth and checkpoints.

persistence.aof_path

The default is ./data/amaquet.aof. The parent directory must be writable and should be on persistent storage. Use an absolute path in a service deployment so changing the process working directory cannot select a different journal.

persistence.fsync

always provides the strongest acknowledged-write durability with the highest write latency. everysec flushes approximately once per second and is the usual balance. no relies on operating-system writeback and provides the weakest crash-durability guarantee. All modes retain transactional replay and CRC integrity checks.

Limits and memory

These limits bound connections, frames, memory reservations, concurrency, uploads, and command execution. Set them with the host’s file-descriptor, memory, and workload ceilings in mind.

limits.max_connections

The default is 10000 native connections. Set it below the file-descriptor and memory capacity of the host, accounting for client pools, TLS sockets, and administration traffic.

limits.max_payload_bytes

The default and hard maximum are 67108864 bytes (64 MiB) per protocol frame. Lowering it reduces the largest single decode allocation. Chunked blob operations are the path for logical values that need multiple frames.

limits.max_memory_bytes

The default 0 means no configured engine data budget. A positive value is an approximate budget for stored values and reservation decisions, not a process-RSS cap. Leave headroom for Go runtime memory, network buffers, indexes, AOF state, and temporary request data.

limits.eviction_policy

noeviction rejects an allocating write at the memory limit. allkeys-lru and allkeys-lfu evict sampled candidates regardless of TTL. volatile-ttl considers only expiring keys and prefers the nearest expiry. Eviction is approximate; if no eligible candidate exists, the write is rejected. DEL and other memory-reducing operations remain available.

limits.max_inflight_requests and limits.max_inflight_per_connection

The defaults are 4096 active commands server-wide and 128 active commands per connection. The global cap protects the process overall; the per-connection cap prevents one multiplexed client from consuming all command capacity.

limits.max_inflight_payload_bytes

The default is 268435456 bytes (256 MiB) across active inbound frames. It must be at least max_payload_bytes. Lower it when many clients can submit large requests concurrently.

limits.max_pending_upload_bytes

The default is 1073741824 bytes (1 GiB) reserved by unfinished chunked uploads. It protects upload spool and reservation capacity from clients that declare large uploads and never complete them.

limits.upload_ttl_ms

The default is 600000 milliseconds (10 minutes), with a minimum of 1000. An upload that remains inactive past this lifetime is discarded. Increase it only for slow links and keep the aggregate pending-upload budget bounded.

limits.command_timeout_ms

The default is 30000 milliseconds. This server-side deadline covers one command and also caps blocking type operations. It is independent of a client’s own dial/request timeout, so clients should choose a compatible value.

In-memory compression

Compression trades CPU time for lower in-memory value size. It is applied only when the configured size and savings thresholds make it worthwhile.

compression.enabled

Compression is enabled by default for supported contiguous values. It is adaptive: values below min_bytes, incompressible values, and results that do not meet the savings threshold remain uncompressed. Disable it when CPU latency is more important than memory reduction.

compression.algorithm

auto tries RLE and LZ4 and retains the smaller candidate. lz4 favors fast block compression, rle favors repeated-byte data, deflate-fast favors a higher ratio at additional CPU cost, and none disables compression. The value is validated at startup.

compression.min_bytes

The default is 1024 bytes. Values smaller than this are not considered for compression. The setting must be non-negative and can be raised to avoid spending CPU on small values.

compression.min_savings_percent

The default is 8, meaning a compressed result must save at least eight percent before being retained. It must be at least 0 and below 100. Higher thresholds avoid marginal compression wins; lower thresholds trade more CPU for memory savings.

data_dir

The default ./data is the runtime root for admin.json, generated bootstrap-token material, upload spools, checkpoints/backups, and related security/runtime files. Amaquet creates it with restrictive permissions. Put it on persistent storage when administration state, upload recovery, or backups must survive restarts. Back it up separately from the AOF journal.

Environment overrides

Environment values are applied after JSON and are useful for containers and service managers. Only the variables below are supported:

Variable	Overrides	Notes
AMAQUET_HOST	protocol.host	Text address.
AMAQUET_PORT	protocol.port	Invalid integers are ignored.
AMAQUET_ADMIN_HOST	admin.host	Text address.
AMAQUET_ADMIN_PORT	admin.port	Invalid integers are ignored.
AMAQUET_ALLOW_INSECURE_AUTH	protocol.allow_insecure_auth	Exact 1 or true enables it.
AMAQUET_ADMIN_ALLOW_INSECURE	admin.allow_insecure	Exact 1 or true enables it.
AMAQUET_BOOTSTRAP_TOKEN	security.bootstrap_token	Runtime-only secret override.
AMAQUET_TLS_CERT	protocol.tls_cert_file	Also sets protocol.tls=true.
AMAQUET_TLS_KEY	protocol.tls_key_file	Also sets protocol.tls=true.
AMAQUET_COMPRESSION	compression.enabled	Disabled only by exact 0 or false.
AMAQUET_COMPRESSION_ALGORITHM	compression.algorithm	Must be a supported algorithm.
AMAQUET_COMPRESSION_MIN_BYTES	compression.min_bytes	Invalid integers are ignored.
AMAQUET_AOF_ENABLED	persistence.aof_enabled	Exact 1 or true enables it.
AMAQUET_AOF_PATH	persistence.aof_path	Runtime path.
AMAQUET_AOF_FSYNC	persistence.fsync	always, everysec, or no.
AMAQUET_MAX_MEMORY_BYTES	limits.max_memory_bytes	Parsed as a signed 64-bit integer.
AMAQUET_EVICTION_POLICY	limits.eviction_policy	Must be a supported policy.
AMAQUET_MAX_CONNECTIONS	limits.max_connections	Must remain positive after merging.
AMAQUET_MAX_INFLIGHT_REQUESTS	limits.max_inflight_requests	Global active-command cap.
AMAQUET_MAX_INFLIGHT_PER_CONNECTION	limits.max_inflight_per_connection	Per-connection active-command cap.
AMAQUET_MAX_INFLIGHT_PAYLOAD_BYTES	limits.max_inflight_payload_bytes	Must be at least max_payload_bytes.
AMAQUET_MAX_PENDING_UPLOAD_BYTES	limits.max_pending_upload_bytes	Aggregate unfinished-upload budget.
AMAQUET_UPLOAD_TTL_MS	limits.upload_ttl_ms	Minimum 1000.
AMAQUET_COMMAND_TIMEOUT_MS	limits.command_timeout_ms	Must be positive.

There are no environment overrides for admin TLS paths, admin.max_sessions, admin.auth_failures_per_minute, limits.max_payload_bytes, or compression.min_savings_percent; configure those in JSON. Environment bootstrap secrets are not copied into the JSON file by runtime configuration saves.

Validation and unsafe combinations

Both ports must be valid. Positive resource limits cannot be zero or negative, max_inflight_payload_bytes cannot be smaller than one frame, and upload_ttl_ms cannot be below one second. Compression and eviction values must match their supported enums. TLS requires both a certificate and a key for the listener being secured.

An authenticated non-loopback native listener requires TLS unless protocol.allow_insecure_auth is explicitly true. A non-loopback admin listener requires HTTPS unless admin.allow_insecure is explicitly true. These checks happen before the sockets are opened, so a configuration error fails closed rather than starting a partially protected service.

Runtime changes and restart behavior

The administration configuration endpoint validates and saves a new public configuration using a temporary file, fsync, and atomic rename. It does not reinitialize listeners, engine memory policy, persistence, or other runtime components in place. When the submitted configuration differs from the running configuration, the response reports restart_required: true; restart the process under the approved service supervisor to apply it.

The bootstrap token is intentionally removed from the public configuration representation. Treat a configuration response as safe to inspect, but continue to protect the original JSON file, environment, token file, private keys, and AOF paths.

Related guidance

Use Installation for a source build and first authenticated request, Authentication and identity for HELLO/AUTH and credential behavior, Persistence and recovery for AOF durability, and Production deployment for supervision, storage, and network topology.