Skip to main content
Version: v5

Configuration Options

Quick reference for all harper-config.yaml top-level sections.

For how to apply configuration (YAML file, environment variables, CLI, Operations API), see Configuration Overview.

http​

Configures the Harper component server (HTTP, REST API, WebSocket). See HTTP Configuration for full details.

http:
  port: 9926
  securePort: 4443
  cors: true
  timeout: 120000
  mtls: false
  logging:
    level: info
    path: ~/hdb/log/http.log
  • sessionAffinity — Route requests from same client to same worker thread (ip or header name)
  • compressionThreshold — Response size threshold for Brotli compression; Default: 1200 (bytes)
  • cors — Enable CORS; Default: true
  • corsAccessList — Allowed domains for CORS requests
  • corsAccessControlAllowHeaders — Access-Control-Allow-Headers value for OPTIONS preflight
  • headersTimeout — Max wait for complete HTTP headers (ms); Default: 60000
  • maxHeaderSize — Max HTTP header size (bytes); Default: 16394
  • requestQueueLimit — Max estimated request queue time (ms) before 503; Default: 20000
  • keepAliveTimeout — Inactivity before closing keep-alive connection (ms); Default: 30000
  • port — HTTP port; Default: 9926
  • securePort — HTTPS port; requires TLS configuration; Default: null
  • http2 — Enable HTTP/2; Default: false (Added in: v4.5.0)
  • timeout — Request timeout (ms); Default: 120000
  • mtls — Enable mTLS authentication for incoming connections; sub-options: user, required, certificateVerification (see Certificate Verification)
  • logging — HTTP request logging (disabled by default, Added in: v4.6.0); sub-options: level, path, timing, headers, id. See Logging Configuration

threads​

Worker thread pool configuration.

threads:
  count: 11
  maxHeapMemory: 300
  • count — Number of worker threads; Default: CPU count minus one
  • maxHeapMemory — Heap limit per thread (MB)
  • heapSnapshotNearLimit — Write a .heapsnapshot file when a thread nears its heap limit (loadable in Chrome DevTools Memory tab); Default: false. See Worker Thread Debugging
  • debug — Enable Node.js inspector; sub-options: port, startingPort, host, waitForDebugger. See Worker Thread Debugging
  • preload Added in: v5.2.0 — Module, or list of modules, to load (via Node's --import) before any Harper or application module on each worker thread. Intended for instrumentation/APM agents that must load first to instrument subsequent module loads. Use the agent's ESM/register entry — e.g. dd-trace/register.js, which registers the loader hooks that instrument worker threads (where Harper runs its work); the plain dd-trace/init (--require) entry only covers the main thread. Bare specifiers resolve against the node_modules of your installed components — so the agent can be shipped as a dependency of a deployed component — and absolute paths are also accepted. Applies to worker threads only (not under Bun).
threads:
  preload: dd-trace/register.js

Or several modules:

threads:
  preload:
    - dd-trace/register.js
    - /opt/instrumentation/agent.mjs
  • preloadRequire Added in: v5.2.0 — Same as preload, but loads modules via Node's --require (CommonJS) instead of --import. Use this for agents that document the --require path and do not need ESM loader hooks (e.g. dd-trace/init, Dynatrace OneAgent). Same resolution rules as preload.
threads:
  preloadRequire: dd-trace/init

authentication​

Authentication and session configuration. Added in: v4.1.0; enableSessions added in v4.2.0. See Authentication Configuration.

authentication:
  authorizeLocal: true
  cacheTTL: 30000
  enableSessions: true
  operationTokenTimeout: 1d
  refreshTokenTimeout: 30d
  • authorizeLocal — Auto-authorize loopback requests as superuser; Default: true
  • cacheTTL — Session cache duration (ms); Default: 30000
  • enableSessions — Cookie-based sessions; Default: true
  • operationTokenTimeout — Access token lifetime; Default: 1d
  • refreshTokenTimeout — Refresh token lifetime; Default: 30d
  • logging — Authentication event logging (Added in: v4.6.0); sub-options: path, level, tag, stdStreams. See Logging Configuration

operationsApi​

Harper Operations API endpoint configuration. See Operations API Overview.

operationsApi:
  network:
    port: 9925
    cors: true
  tls:
    certificate: ~/hdb/keys/certificate.pem
    privateKey: ~/hdb/keys/privateKey.pem
  • componentFile.maxSize — Maximum file size in bytes returned by get_component_file. Requests for files larger than this limit are rejected with HTTP 413. Default: 5242880 (5 MB)
  • network.cors / network.corsAccessList — CORS settings
  • network.domainSocket — Unix socket path for CLI communication; Default: <rootPath>/hdb/operations-server
  • network.headersTimeout / network.keepAliveTimeout / network.timeout — Timeout settings (ms)
  • network.port — Operations API port; Default: 9925
  • network.securePort — HTTPS port; Default: null
  • tls — TLS override for the Operations API; sub-options: certificate, certificateAuthority, privateKey. See tls

tls​

Global TLS configuration for HTTPS and TLS sockets (used by HTTP and MQTT). Can be a single object or an array for SNI. See TLS and Certificate Management.

tls:
  certificate: ~/hdb/keys/certificate.pem
  certificateAuthority: ~/hdb/keys/ca.pem
  privateKey: ~/hdb/keys/privateKey.pem
  • certificate — Path to TLS certificate; Default: <rootPath>/keys/certificate.pem
  • certificateAuthority — Path to CA file; Default: <rootPath>/keys/ca.pem
  • privateKey — Path to private key; Default: <rootPath>/keys/privateKey.pem
  • ciphers — Allowed TLS cipher suites

mqtt​

MQTT protocol configuration. Added in: v4.2.0. See MQTT Configuration.

mqtt:
  network:
    port: 1883
    securePort: 8883
  webSocket: true
  requireAuthentication: true
  • network.port — Insecure MQTT port; Default: 1883
  • network.securePort — Secure MQTT port; Default: 8883
  • network.mtls — Enable mTLS for MQTT connections; sub-options: user, required, certificateAuthority, certificateVerification
  • webSocket — Enable MQTT over WebSocket on HTTP port; Default: true
  • requireAuthentication — Require credentials or mTLS; Default: true
  • logging — MQTT event logging (Added in: v4.6.0); sub-options: path, level, tag, stdStreams. See Logging Configuration

logging​

Application logging. Added in: v4.1.0; per-component logging added in v4.6.0. See Logging Configuration.

logging:
  level: warn
  root: ~/hdb/log
  stdStreams: false
  auditLog: false
  rotation:
    interval: 1D
    maxSize: 100M
  • level — Log verbosity (trace → debug → info → warn → error → fatal → notify); Default: warn
  • file — Write to file; Default: true
  • root — Log directory; Default: <rootPath>/log
  • path — Explicit log file path (overrides root)
  • stdStreams — Write to stdout/stderr; Default: false
  • console — Include console.* output; Default: true
  • auditLog — Enable table transaction audit logging; Default: false
  • auditRetention — Audit log retention duration; Default: 3d
  • external — Logging for components using the logger API; sub-options: level, path
  • rotation.enabled / rotation.compress / rotation.interval / rotation.maxSize / rotation.path — Log file rotation (activates when interval or maxSize is set)
  • auditAuthEvents.logFailed / auditAuthEvents.logSuccessful — Log failed/successful authentication events; Default: false

node​

This node's identity within the cluster. See Replication.

node:
  hostname: server-one
  • hostname Changed in: v5.3.0 — This node's identity: it becomes the node's TLS certificate common name and the host that replication advertises to peers and dials to reach this node. Must be a bare hostname or IP literal (e.g. server-one, 10.0.0.5, or the unbracketed IPv6 form ::1) — not a URL and not host:port. Harper fails to start if the value carries a scheme, port, path, credentials, query string, or fragment, is a bracketed IPv6 literal ([::1]), or is not a string; the startup error names the offending value and the reason. Earlier versions accepted such values and silently corrupted certificate matching and replication — a node configured as http://host:9926 advertised and dialed a host literally named http. The same requirement applies to replication.hostname. If unset, Harper uses the first valid bare host among replication.hostname, the host in replication.url, the TLS certificate common name, and the Operations API host, falling back to 127.0.0.1.

replication​

Native WebSocket-based replication (Plexus). Added in: v4.4.0. See Replication and Clustering.

replication:
  hostname: server-one
  url: wss://server-one:9933
  databases: '*'
  routes:
    - wss://server-two:9933
  • hostname Changed in: v5.3.0 — This instance's hostname within the cluster. Subject to the same bare hostname or IP literal requirement as node.hostname — a URL, host:port, or non-string value fails startup. When both are set, node.hostname wins.
  • url — WebSocket URL peers use to connect to this instance
  • databases — Databases to replicate; Default: "*" (all). Each entry supports name and sharded
  • routes — Peer nodes; URL strings or {hostname, port, startTime, revokedCertificates} objects
  • port — Replication port
  • securePort — Secure replication port; Default: 9933 (changed from 9925 in v4.5.0)
  • enableRootCAs — Verify against Node.js Mozilla CA store; Default: true
  • blobTimeout — Blob transfer timeout (ms); Default: 120000
  • blobGapReconnectMs — Interval (ms) for the blob-gap watchdog: when a transient blob save failure pins a replication resume cursor, the connection is forced to reconnect on this cadence so the gapped blob is re-streamed and, during a bulk copy, the copy resumes from the last banked cursor. Lower values heal gaps faster at the cost of more reconnects on a link whose faults never heal; Default: the blobTimeout value
  • copyCursorFlushBytes — Bytes of applied bulk-copy data between durable flushes of the copy resume cursor (RocksDB); Default: 67108864
  • copyCursorFlushIntervalMs — Maximum time (ms) between durable flushes of the bulk-copy resume cursor (RocksDB); Default: 5000
  • blobSendDrainTimeout — Maximum time (ms) a worker waits for in-flight replication blob sends to finish before shutting down during a restart, so a rolling restart (e.g., a component deploy reload) doesn't interrupt a transfer in progress. Only sends that are still making progress are waited on; 0 disables draining; Default: 600000
  • failOver — Failover to alternate node if peer unreachable; Default: true
  • shard — Shard ID for traffic routing; see Sharding
  • mtls.certificateVerification — Certificate revocation checking (CRL/OCSP) for replication connections; see Certificate Verification
  • logging — Replication event logging; sub-options: path, level, tag, stdStreams. See Logging Configuration

storage​

Database storage configuration. See Storage Tuning for guidance on tuning these options for production workloads, Database Overview for general database concepts, and Compaction for reclaiming space inside existing files.

storage:
  path: ~/hdb/database
  caching: true
  compression: true
  compactOnStart: false
  engine: rocksdb
  • engine — The database storage engine to use for new databases. Currently supported engines are rocksdb and lmdb. The default is rocksdb. Existing databases will use the engine that was used when they were created.
  • writeAsync — Disable disk sync for higher throughput (disables durability guarantees); Default: false
  • caching — In-memory record caching; Default: true
  • compression — LZ4 record compression; Default: true (enabled by default since v4.3.0). Sub-options: dictionary, threshold
  • compactOnStart — Compact all non-system databases on startup; Default: false (Added in: v4.3.0)
  • compactOnStartKeepBackup — Retain compaction backups; Default: false
  • maxTransactionQueueTime — Per-thread write-commit duration threshold for HTTP 503 backpressure; see Storage Tuning; Default: 45s
  • noReadAhead — Advise OS against read-ahead; Default: false
  • prefetchWrites — Prefetch before write transactions; Default: true
  • randomAccessFields Added in: v5.1.0 — Encode records as typed random-access structures, so a single field can be read without decoding the whole record. Best for tables whose records have a stable set of fields with stable types; leave off for wide, sparse, or variably typed schemas. Read by each table when its store opens, so a change applies to existing tables on restart, and ignored entirely by tables declaring the @table(randomAccessFields:) directive; Default: false. See Storage Tuning — Record Encoding
  • path — Database files directory; Default: <rootPath>/database
  • backupPath — Directory for managed database backups (created by create_backup), one subdirectory per database; Default: <rootPath>/backup (Added in: v5.2.0)
  • blobPaths — Blob storage directory or directories; Default: <rootPath>/blobs (Added in: v4.5.0)
  • pageSize — Database page size (bytes); Default: OS default
  • reclamation.threshold — Free-space ratio below which reclamation begins evicting from caching tables; Default: 0.4 (Added in: v4.5.0)
  • reclamation.interval — Free-space check interval; Default: 1h
  • reclamation.evictionFactor — Heuristic factor for early eviction under disk pressure; Default: 100000. See Storage Tuning — Reclamation
  • rocks.blockCacheSize — RocksDB shared block cache size in bytes; Default: 25% of constrained memory. See Storage Tuning — RocksDB Memory (Added in: v5.1.0)
  • rocks.writeBufferManagerSize — Process-wide cap (bytes) on RocksDB memtable memory across all databases. 0 disables; Default: one third of blockCacheSize (enabled). See Storage Tuning — RocksDB Memory (Added in: v5.1.0)
  • rocks.writeBufferManagerCostToCache — When enabled, memtable memory and the block cache share a single, unified memory pool. During heavy write bursts, the block cache dynamically shrinks to give memtables more room. Once those memtables flush to disk, the block cache automatically reclaims that memory space. Default: true. Has no effect when writeBufferManagerSize is 0. (Added in: v5.1.0)
  • rocks.writeBufferManagerAllowStall — Stall writes when memtable memory exceeds writeBufferManagerSize (hard cap) instead of allowing brief overshoot with more aggressive flushing (soft cap); Default: true. (Added in: v5.1.0)

databases​

Per-database and per-table file path overrides. Must be set before the database/table is created. See Database Overview.

databases:
  myDatabase:
    path: /data/myDatabase
    auditPath: /data/myDatabase-audit
    tables:
      myTable:
        path: /data/myTable
  • <dbName>.path — Database files directory
  • <dbName>.auditPath — Audit log directory for this database
  • <dbName>.tables.<tableName>.path — Table files directory

analytics​

Analytics aggregation configuration. See Analytics Overview.

analytics:
  aggregatePeriod: 60
  replicate: false
  • aggregatePeriod — Aggregation interval (seconds); Default: 60 (Added in: v4.5.0)
  • storageInterval — Aggregation cycles between storage-volume measurements (0 disables); Default: 10
  • replicate — Replicate analytics data across cluster; Default: false
  • logging — Per-subsystem logger override for analytics writes. See Logging Configuration

localStudio​

Local Harper Studio GUI. See Studio.

localStudio:
  enabled: true
  • enabled — Enable local Studio at http://localhost:<port>; Default: false

componentsRoot​

Path to local component files. Added in: v4.2.0 (previously customFunctionsRoot). See Components.

componentsRoot: ~/hdb/components

rootPath​

Root directory for all Harper persistent data, config, logs, and components.

rootPath: /var/lib/harper

agent​

Added in: v5.2.0

Built-in Harper agent — an LLM loop that operates this instance through Harper's own operations, scoped filesystem access, followup scheduling, the V8 inspector, and outbound HTTP. Disabled by default, so it never incurs LLM cost unless you turn it on. Driven through the Agent operations, which also describe the privilege boundary before you enable it.

agent:
  enabled: true
  model: default
  maxTurns: 50
  autoApprove: false
  allowDestructive: false
  user: hdb_agent
  • enabled — Enable the agent component; Default: false
  • provider — Recorded on the session but not yet used to route the model call — only model reaches the provider. Set the provider through the models configuration instead
  • model — Model id override, passed through to the model call; Default: the models generative default
  • maxTurns — Maximum tool-call iterations in a single run; Default: 50
  • maxCostUsd — Intended per-run cost ceiling. Not enforced — it is a stored setting only, and nothing checks spend against it; Default: 5.00
  • autoApprove — Run without per-action approval gates; Default: false
  • allowDestructive — Include the tools marked destructive in the agent's toolset: write_file, the inspector's code-evaluation tools, and any operations tool carrying MCP's destructiveHint (drop_table, delete, restart, set_configuration, ...). When false they are removed entirely rather than gated. That hint comes from a curated set in core which does not cover every damaging operation, so this is not a complete safety boundary on its own — see Agent operations; Default: false
  • user — Harper user the agent's operations tools run as; the filesystem, HTTP, schedule, and inspector tools always run at process privilege regardless. If it cannot be resolved and it is not the default, the agent fails closed and runs with no operations tools; Default: hdb_agent, which falls back to a super_user bootstrap identity
  • componentsScope — Filesystem write scope for component edits, relative to rootPath; Default: the full componentsRoot
  • systemPromptAppend — Operator text appended to the agent's system prompt

enabled, provider, model, maxTurns, maxCostUsd, autoApprove, allowDestructive, and systemPromptAppend can also be changed at runtime with set_agent_config, which applies in memory only. enabled is the exception worth knowing: it cannot switch the agent on, because with the agent disabled at startup no agent operation is registered at all.

applications​

Added in: v5.0.0

applications:
  lockdown: freeze-after-load
  moduleLoader: vm-current-context
  dependencyLoader: auto
  allowedSpawnCommands:
    - npm
    - node
  • lockdown — Indicates if intrinsic/built-in objects should be locked down/frozen. This provides additional security and protection against prototype pollution attacks. The default is freeze-after-load, which freezes the important built-in objects once all components have loaded, so component initialization can still modify them. This can also be set to freeze (freeze before any application code loads), none, or ses (lockdown provided by the ses package, which is more strict). See Intrinsic Lockdown.
  • moduleLoader — The method used to load modules (and isolate the application). The default is vm-current-context, which uses Node's VM module loader in Harper's own context so applications share JavaScript intrinsics. This can also be set to vm (VM loader with a separate context and its own intrinsics per application), native (standard Node module loader), or compartment, which uses the ses implementation of the proposed Compartment functionality. See Module Loader Modes.
  • dependencyLoader — The application module loader can be used to load packages/dependencies (installed as dependencies from the package.json). The default is 'auto', which only use the VM module loader if the package specifies harper as a dependency. This can also be set to app to always use the application module loader or native to always native module loader for packages.
  • allowedSpawnCommands - This lists the specific commands that can be spawned by the application (using child_process's spawn() and execFile() functions). You can add commands that your application will need to launch (this is to protect against malicious code spawning processes). Only the first token of the command is matched, spawning also requires a mandatory name option, and the call is subject to a node-wide single-process lock — see Child Processes for the full contract.

Component Configuration​

Installed components are configured directly at the root of harper-config.yaml using the component name as the key — not nested under a components: section. See Components.

my-component:
  package: 'HarperDB-Add-Ons/my-component'
  port: 4321
  • <component-name>.package — NPM package name, GitHub repo (user/repo), or local path
  • <component-name>.port — Port for the component; Default: value of http.port