Configuration reference - Hivenet Router

Hivenet Router is configured through command-line flags, environment variables, and two optional YAML configuration surfaces:

auth.yaml for client and administrator authentication
policy YAML for routing, fallback, and dynamic gates

This page covers process-level router and agent configuration. See auth.yaml reference and Policy YAML reference for the file schemas.

View the installed options

Use the binary’s built-in help to confirm the options available in the version you deployed:

./bin/hivenet-router --help

./bin/hivenet-agent --help

For API-key generation:

./bin/hivenet-router keygen --help

The environment-variable prefix is exactly:

hivenet_router_

Environment-variable names are case-sensitive on Linux. Use the capitalization shown in this reference.

Configuration precedence

The router loads configuration in this order:

Command-line flag
  overrides
Environment variable
  overrides
Built-in default

For example:

export HIVENET_ROUTER_HTTP_PORT=":8081"

./bin/hivenet-router \
  --http-port :8082 \
  ...

The router listens on:

:8082

Agent precedence

Most agent settings are available only as command-line flags. The current agent reads these Hivenet Router environment variables directly:

HIVENET_ROUTER_JWT_SECRET
HIVENET_ROUTER_GPU_MODEL
HIVENET_ROUTER_DEPLOYMENT_ID
HIVENET_ROUTER_REPLICA_ID

Other agent environment variables that resemble flag names are not loaded automatically. For example, this does not currently configure the agent:

export HIVENET_ROUTER_CAPACITY=20

Use:

./bin/hivenet-agent \
  --capacity 20 \
  ...

instead.

Do not assume that every flag has an environment-variable equivalent.Only the mappings explicitly shown on this page are implemented.

Value formats

Durations

Duration flags and environment variables use Go duration syntax:

500ms
5s
2m
1h
1h30m

Examples:

--request-timeout 5m
--engine-sample-interval 500ms
--session-ttl 1h

--disk-db-ttl is different. It accepts an integer number of days rather than a duration string.

HTTP and gRPC listen addresses

Router HTTP, gRPC, and metrics values are complete TCP listen addresses. Listen on every interface:

:8080

Listen only on loopback:

127.0.0.1:8080

libp2p ports

The router’s --p2p-port accepts a port without a colon:

libp2p announce and bootstrap addresses use multiaddress syntax:

/ip4/203.0.113.10/tcp/9000
/dns4/router.example.com/tcp/9000

Paths

Relative paths are resolved from the process’s working directory. For a system service or container, prefer explicit paths such as:

/etc/hivenet-router/auth.yaml
/etc/hivenet-router/policy.yaml
/var/lib/hivenet-router/badger
/var/lib/hivenet-router/agent-identity.key

Router network settings

Flag	Environment variable	Default	Description
`--http-port`	`HIVENET_ROUTER_HTTP_PORT`	`:8080`	Client, health, and administration HTTP listen address
`--grpc-port`	`HIVENET_ROUTER_GRPC_PORT`	`:50051`	Agent-authentication gRPC listen address
`--metrics-port`	`HIVENET_ROUTER_METRICS_PORT`	`:2112`	Prometheus metrics listen address
`--p2p-port`	`HIVENET_ROUTER_P2P_PORT`	`9000`	Router libp2p TCP port
`--p2p-listen-addr`	—	`127.0.0.1`	IP address used to bind the router’s libp2p host
`--p2p-announce-addr`	—	Empty	Dialable multiaddress advertised to agents
`--p2p-max-conns-per-ip`	`HIVENET_ROUTER_P2P_MAX_CONNS_PER_IP`	`32`	Maximum libp2p connections from one IPv4 `/32` or IPv6 `/56` source prefix

HTTP API

The HTTP server exposes:

/health
/v1/*
/admin/*

Use a reverse proxy or another ingress layer for TLS. The HTTP server does not enable HTTPS itself.

Metrics

The metrics server is separate from the main HTTP API:

http://<router-host>:2112/metrics

It has no built-in authentication. Keep it on a private interface or protect it through network controls.

Remote agents

The router’s libp2p host binds to loopback by default:

127.0.0.1

For agents on other machines:

--p2p-listen-addr 0.0.0.0

When the bind address is not the address agents should dial, also set:

--p2p-announce-addr \
  /dns4/router.example.com/tcp/9000

The announce value must be a valid multiaddress. An invalid value stops router startup.

Agents behind shared NAT

Agents behind one NAT or egress gateway appear to libp2p as connections from one source IP. Set:

--p2p-max-conns-per-ip <limit>

comfortably above the number of agents sharing that address. A practical starting point is:

at least 2 × the maximum agent count behind one egress IP

The additional room covers reconnect overlap during restarts and fleet rollouts.

Router routing and backpressure settings

Flag	Environment variable	Default	Description
`--policy-file`	`HIVENET_ROUTER_POLICY_FILE`	Empty	Global routing-policy YAML file
`--policy-model-dir`	`HIVENET_ROUTER_POLICY_MODEL_DIR`	Empty	Directory containing global and per-model policies
`--max-tries-per-step`	`HIVENET_ROUTER_MAX_TRIES_PER_STEP`	`3`	Default forward attempts for policy steps without `max_tries`
`--queue-size`	`HIVENET_ROUTER_QUEUE_SIZE`	`100`	Capacity of the router’s global pending-request channel
`--queue-depth`	`HIVENET_ROUTER_QUEUE_DEPTH`	`30`	Maximum capacity waiters per model; `0` disables model queues
`--max-concurrent`	—	`50`	Maximum simultaneous router-to-agent request forwards
`--request-timeout`	`HIVENET_ROUTER_REQUEST_TIMEOUT`	`60s`	Deadline for the complete router-side request operation
—	`HIVENET_ROUTER_MAX_REQUEST_BYTES`	`10485760`	Maximum request body size for `/v1/*` endpoints in bytes; `0` disables the limit

Built-in policy

When no policy file or directory is configured, Hivenet Router uses:

least-loaded

with:

no static filters
no dynamic exclusions
no local fallback steps
no provider fallback

Policy-file precedence

When both are configured:

--policy-file
--policy-model-dir

and the model-policy directory contains:

_default.yaml

the directory’s _default.yaml becomes the global policy. Hivenet Router logs a warning that it replaced the standalone policy file. Named policy files in the directory can claim specific models.

Global request queue

--queue-size controls the buffered request channel before processor work begins. When the channel remains full for the handler’s enqueue window, Hivenet Router returns:

503 queue_full

Use a positive value.

Per-model wait queue

--queue-depth controls how many requests can wait for capacity for each model.

--queue-depth 0

disables capacity waiting. A request encountering full eligible agents then advances directly through its fallback path.

Concurrent forwards

--max-concurrent limits requests actively being forwarded to agents. It is separate from:

the global request-channel size
the per-model wait queue
each agent’s declared capacity

Request deadline

--request-timeout covers:

time waiting for processor concurrency
policy evaluation
time waiting in a per-model capacity queue
retries and fallback steps
agent forwarding
response or stream handling

A longer client or agent timeout cannot extend a shorter router deadline.

Router health and session settings

Flag	Environment variable	Default	Description
`--health-check-interval`	—	`5s`	Frequency of router health-monitor passes
`--heartbeat-interval`	—	`5s`	Heartbeat cadence sent to agents during authentication
`--unhealthy-after`	—	`15s`	Time without a heartbeat before an agent is marked unhealthy
`--remove-after`	—	`30s`	Time without a heartbeat before an agent is removed
`--session-ttl`	`HIVENET_ROUTER_SESSION_TTL`	`1h`	Lifetime of an agent session token

Keep these relationships:

heartbeat interval
  <
unhealthy threshold
  <
removal threshold

The defaults are:

5s < 15s < 30s

The router does not currently reject every inconsistent combination of these timing values.Changing them makes you responsible for preserving a coherent ordering.

Session lifetime

The session TTL must be longer than:

5 minutes

The router refuses to start when it is five minutes or less because agents begin renewal five minutes before expiration. Agents normally:

authenticate once
receive a one-hour session
renew five minutes before expiry
retry failed renewal after 30 seconds

Router storage settings

Flag	Environment variable	Default	Description
`--disk-db-path`	`HIVENET_ROUTER_DISK_DB_PATH`	`./badger_disk`	Persistent BadgerDB directory
`--disk-db-ttl`	—	`30`	Entry lifetime in days; `0` disables expiry
`--universal-flush-interval`	—	`30s`	Frequency for flushing per-agent history and persistent quota changes
`--reset-disk-db`	—	`false`	Delete the complete persistent database before startup

The persistent database can contain:

per-agent request and token history
SRTT and RTTVAR
disconnection and failure history
daily token state when the Badger quota backend is active

Database reset

--reset-disk-db

deletes the configured database directory before the router opens it.

Do not use --reset-disk-db as a normal recovery step.It removes persisted agent history and Badger-backed daily quota state from that directory.

Universal flush interval

The same interval is currently used for:

universal per-agent history flushes
Badger-backed quota flushes

Request-per-minute quota buckets remain in memory even when the Badger quota backend is enabled.

Router security and authentication settings

Flag	Environment variable	Default	Description
`--jwt-secret-file`	`HIVENET_ROUTER_JWT_SECRET`	Required	Read the shared agent secret from a file, or provide its raw value through the environment
`--auth-config-file`	`HIVENET_ROUTER_AUTH_CONFIG`	Empty	Path to `auth.yaml`

Agent JWT secret

The router requires a shared secret containing at least:

32 bytes

Recommended file-based configuration:

./bin/hivenet-router \
  --jwt-secret-file /etc/hivenet-router/jwt.secret \
  ...

Environment-based configuration:

export HIVENET_ROUTER_JWT_SECRET="<shared-secret>"

When both are provided, --jwt-secret-file wins. The file’s leading and trailing whitespace is removed, so a final newline is safe. The value must match every agent exactly. Changing it changes:

JWT validation
the router’s derived gRPC TLS identity
the public key pinned by agents

Rotate it as a coordinated router-and-agent change.

Authentication file

--auth-config-file /etc/hivenet-router/auth.yaml

controls:

client API authentication
administrator authentication mode
static client keys
model access
quotas
static expiration

See auth.yaml reference.

Router environment-only settings

These settings do not have equivalent router command-line flags.

Environment variable	Default	Description
`HIVENET_ROUTER_AUTH_MODE`	`none` when no file is configured	API auth mode when `auth.yaml` is absent
`HIVENET_ROUTER_ADMIN_API_KEYS`	Empty	Comma-separated raw administrator keys
`HIVENET_ROUTER_QUOTA_BACKEND`	`memory`	`memory` or `badger`
`HIVENET_ROUTER_OPENAI_API_KEY`	Empty	OpenAI credential for provider fallback
`HIVENET_ROUTER_ANTHROPIC_API_KEY`	Empty	Anthropic credential for provider fallback
`HIVENET_ROUTER_AUDIT_LOG_PATH`	`/var/log/hivenet-router/audit.jsonl`	Structured audit-log path
`HIVENET_ROUTER_MAX_REQUEST_BYTES`	`10485760`	Maximum request body size for `/v1/*` endpoints in bytes; `0` disables the limit
`HIVENET_ROUTER_ADMIT_FRACTION`	`0.90`	Fraction of `admit_budget_tokens` available for occupancy admission; valid range `(0, 1]`
`HIVENET_ROUTER_ADMIT_PARK_TIMEOUT`	`250ms`	Maximum time an over-budget request waits for occupancy to free; `0` rejects immediately
`HIVENET_ROUTER_RPM_BURST_SECONDS`	`0`	RPM bucket burst window in seconds; `0` keeps a full minute of burst capacity, valid range `[0, 60)`
`HIVENET_ROUTER_ALLOW_INSECURE_ADMIN`	`false`	Set to `true` to permit unauthenticated `/admin/*` endpoints when administrator mode is `none`; development and testing only

`HIVENET_ROUTER_AUTH_MODE`

Accepted API modes are:

none
api-key
dynamic

This variable is read only when no auth configuration file is set. When auth.yaml is present, its:

api:
  mode:

value takes precedence.

Setting:

HIVENET_ROUTER_AUTH_MODE=api-key

without an auth.yaml file does not provide any static keys.Startup fails because the key list is empty. Use an auth file for static API-key mode.

Dynamic mode automatically requires administrator authentication and:

HIVENET_ROUTER_ADMIN_API_KEYS

`HIVENET_ROUTER_ADMIN_API_KEYS`

Provide one or more raw keys separated by commas:

export HIVENET_ROUTER_ADMIN_API_KEYS="admin-key-1,admin-key-2"

Whitespace around values is removed. Administrator keys are separate from client API keys.

`HIVENET_ROUTER_ALLOW_INSECURE_ADMIN`

The router refuses to start with unauthenticated administrator endpoints unless you explicitly set:

export HIVENET_ROUTER_ALLOW_INSECURE_ADMIN=true

Use this only for isolated local development or testing. In shared, remote, or production environments, configure administrator API-key authentication instead.

`HIVENET_ROUTER_MAX_REQUEST_BYTES`

The default maximum request body size for /v1/* endpoints is:

10485760 bytes

which is 10 MiB. Requests above the configured limit are rejected with HTTP 413 before routing. Set another byte value to change the limit, or:

export HIVENET_ROUTER_MAX_REQUEST_BYTES=0

to disable it. A reverse proxy may enforce a smaller limit before the request reaches Hivenet Router.

Admission environment variables

HIVENET_ROUTER_ADMIT_FRACTION scales a policy’s admit_budget_tokens before the router admits token-weighted occupancy. It defaults to 0.90; invalid values or values outside (0, 1] leave the default unchanged. HIVENET_ROUTER_ADMIT_PARK_TIMEOUT bounds how long an over-budget request waits for occupancy to free. It uses Go duration syntax, defaults to 250ms, and accepts 0 for immediate rejection. Negative or invalid values leave the default unchanged. HIVENET_ROUTER_RPM_BURST_SECONDS changes the burst capacity of both flat and per-model RPM buckets. With a value from 1 through 59, burst capacity is floor(effective RPM × seconds / 60), with a minimum of 1. The default 0 preserves the legacy full-minute burst. Invalid values and values outside [0, 60) leave that default unchanged. See Admission control for policy fields, footprint calculation, and error responses.

`HIVENET_ROUTER_QUOTA_BACKEND`

Supported values are:

memory
badger

memory:

keeps RPM and daily token state in process memory
loses both after a router restart

badger:

keeps RPM buckets in memory
periodically persists daily token use
restores daily token state after restart

Any other value stops router startup.

Provider credentials

Provider fallback credentials are read when the router starts:

export HIVENET_ROUTER_OPENAI_API_KEY="<openai-key>"
export HIVENET_ROUTER_ANTHROPIC_API_KEY="<anthropic-key>"

If an active policy refers to a provider whose key is absent, startup fails. Changing a provider credential requires a router restart.

Audit path

export HIVENET_ROUTER_AUDIT_LOG_PATH=/var/log/hivenet-router/audit.jsonl

The router creates the parent directory when possible. When it cannot open the file, it writes audit JSON to standard output instead. Changing the path requires a router restart.

Router flag reference

The complete current router flag set is:

Flag	Environment variable	Default
`--http-port`	`HIVENET_ROUTER_HTTP_PORT`	`:8080`
`--grpc-port`	`HIVENET_ROUTER_GRPC_PORT`	`:50051`
`--metrics-port`	`HIVENET_ROUTER_METRICS_PORT`	`:2112`
`--p2p-port`	`HIVENET_ROUTER_P2P_PORT`	`9000`
`--p2p-listen-addr`	—	`127.0.0.1`
`--p2p-announce-addr`	—	Empty
`--p2p-max-conns-per-ip`	`HIVENET_ROUTER_P2P_MAX_CONNS_PER_IP`	`32`
`--queue-size`	`HIVENET_ROUTER_QUEUE_SIZE`	`100`
`--request-timeout`	`HIVENET_ROUTER_REQUEST_TIMEOUT`	`60s`
`--health-check-interval`	—	`5s`
`--unhealthy-after`	—	`15s`
`--remove-after`	—	`30s`
`--heartbeat-interval`	—	`5s`
`--disk-db-path`	`HIVENET_ROUTER_DISK_DB_PATH`	`./badger_disk`
`--reset-disk-db`	—	`false`
`--disk-db-ttl`	—	`30` days
`--universal-flush-interval`	—	`30s`
`--max-concurrent`	—	`50`
`--policy-file`	`HIVENET_ROUTER_POLICY_FILE`	Empty
`--policy-model-dir`	`HIVENET_ROUTER_POLICY_MODEL_DIR`	Empty
`--max-tries-per-step`	`HIVENET_ROUTER_MAX_TRIES_PER_STEP`	`3`
`--queue-depth`	`HIVENET_ROUTER_QUEUE_DEPTH`	`30`
`--session-ttl`	`HIVENET_ROUTER_SESSION_TTL`	`1h`
`--jwt-secret-file`	`HIVENET_ROUTER_JWT_SECRET` contains the raw value	Required
`--auth-config-file`	`HIVENET_ROUTER_AUTH_CONFIG`	Empty

Agent backend settings

Flag	Environment variable	Default	Description
`--engine`	—	`vllm`	Inference-engine adapter
`--backend-url`	—	`http://localhost:8888`	Base URL of the local inference server
`--model`	—	Empty	Public model ID override
`--health-url`	—	Empty	Health endpoint for a custom engine
`--capability`	—	`llm`	`llm`, `embedding`, or `reranker`
`--capacity`	—	`10`	Maximum concurrent requests assigned to the agent
`--http-timeout`	—	`120s`	Backend HTTP request timeout
`--stream-write-timeout`	—	`60s`	Rolling timeout for writing each stream chunk to the router

Supported engines

Accepted values are:

vllm
ollama
sglang
llamacpp
infinity
custom

Model discovery

When --model is empty, supported engine adapters try to discover a model from the backend. Use an explicit model value when:

the backend exposes several models
the client-facing alias must remain stable
backend discovery is unreliable
the custom engine is selected

A custom engine requires both:

--model
--health-url

Capability

Accepted values are:

llm
embedding
reranker

The router combines the model name and capability when selecting an agent. Ollama currently cannot be registered with:

--capability reranker

because its integration does not expose the required reranking endpoint.

Capacity

Capacity must be positive. It is an operator-defined concurrency limit, not a value calculated from GPU memory or model size. The router rejects agent authentication when the reported capacity is zero or negative.

Backend and router timeouts

The agent’s default backend HTTP timeout is:

120s

The router’s default request timeout is:

60s

The shorter router deadline usually ends the client operation first.

Stream write timeout

--stream-write-timeout is a rolling per-chunk deadline. When the router or another receiver stops reading a stream, the agent eventually releases the blocked write rather than holding the libp2p stream indefinitely. Set:

--stream-write-timeout 0

to disable it.

Agent router and libp2p settings

Flag	Environment variable	Default	Description
`--router-grpc`	—	`localhost:50051`	Router gRPC authentication address; the response supplies the router’s libp2p connection details
`--router-p2p`	—	`/ip4/127.0.0.1/tcp/9000`	Deprecated no-op retained for CLI compatibility
`--identity-path`	—	`./agent_identity.key`	Persistent Ed25519 libp2p private-key file
`--p2p-listen-port`	—	`0`	Local libp2p port; agents initiate the router connection and normally do not need a fixed inbound port
`--jwt-secret-file`	`HIVENET_ROUTER_JWT_SECRET`	Required	Shared agent-authentication secret

Router discovery

The agent currently obtains the router’s actual libp2p addresses from the gRPC authentication response. The accepted:

--router-p2p

flag is not read by the current connection sequence. Configure:

--router-grpc

and make sure the router advertises a reachable libp2p address through:

--p2p-announce-addr

when necessary.

Persistent identity

Use a persistent identity path:

--identity-path \
  /var/lib/hivenet-router/agent-identity.key

Preserving this file preserves the agent’s peer ID. A stable peer ID lets the router associate the agent with earlier:

request counters
token counts
SRTT and RTTVAR
disconnection history

Agent connection direction

Agents initiate their libp2p connection to the router after successful gRPC authentication. The router forwards inference traffic over that established connection rather than opening a new inbound connection to the agent. The default:

--p2p-listen-port 0

lets the operating system choose a local port. A fixed port is rarely needed and does not create a requirement to expose that port to the router.

Do not add inbound agent firewall rules, public agent port mappings, or NAT forwarding solely for Hivenet Router request forwarding. Agent hosts need outbound access to the router’s gRPC and libp2p ports.

Agent metadata settings

Flag	Environment variable	Default	Description
`--version`	—	Build version; `dev` in an unversioned local build	Version recorded in agent metadata
`--region`	—	`UE-France`	Operator-defined location label
`--organization`	—	`Unknown`	Operator or infrastructure-provider label
`--machine`	—	`Unknown`	Machine label
`--tags`	—	`production`	Comma-separated routing tags
`--gpu-model`	`HIVENET_ROUTER_GPU_MODEL`	Empty	Operator-defined GPU label
`--deployment-id`	`HIVENET_ROUTER_DEPLOYMENT_ID`	Empty	Deployment identifier used in tenant metrics
`--replica-id`	`HIVENET_ROUTER_REPLICA_ID`	Empty	Stable replica identifier used with deployment ID by external schedulers
`--hide-llm`	—	`false`	Set the aggregated model’s `hide_llm` metadata flag; this does not currently remove the model from discovery
`--llm-pretty-name`	—	Empty	Human-readable model name
`--llm-info`	—	Empty	Short model description

Region default

The current code default is literally:

UE-France

This is an operator-defined label rather than a validated region code. Override it with the convention used in your deployment:

--region EU-France

or another stable value.

Region, organization, machine, tags, and GPU model become routing and observability labels.Keep them stable and bounded. Do not put user IDs, request IDs, timestamps, or other unbounded values in these fields.

Version

Release builds can inject a version at build time. A local build without an injected value reports:

dev

The --version flag changes registration metadata only. It does not select or install another agent software version.

GPU model

--gpu-model is not detected automatically through NVML. Set a consistent operator-defined value when routing policies use:

match:
  gpu_model:

Deployment ID

The deployment ID is included in agent registration and used in tenant request metrics. It may be empty in local or bare-metal deployments that do not have a separate deployment identity.

Replica ID

--replica-id supplies a stable identifier for one agent replica. When --deployment-id is also set, the two values form a join key for external schedulers and registration-stream consumers.

`hide_llm` metadata

An agent with:

--hide-llm

sets the aggregated model object’s:

{
  "hide_llm": true
}

metadata flag. The current catalog implementation still includes that model in /v1/models. Do not use this flag as an access-control or reliable discovery-hiding mechanism. Use API-key model restrictions to control which models a caller can discover and invoke.

Agent telemetry settings

Flag	Environment variable	Default	Description
`--hardware-sample-interval`	—	`2s`	GPU, CPU, and system-memory collection interval
`--engine-sample-interval`	—	`500ms`	Supported inference-engine metrics scrape interval
`--routing-signal-interval`	—	`500ms`	Frequency for sending cached hardware and engine data to the router
`--gpu-devices-file`	—	Empty	File containing assigned NVIDIA GPU UUIDs

Sampling and push intervals

Sampling and pushing are independent. For example:

Hardware sample: 2s
Routing signal: 500ms

causes the same cached hardware snapshot to be sent several times before the next sample. Reducing only the routing-signal interval does not increase hardware collection frequency.

GPU-device file

The file accepts NVIDIA GPU UUIDs separated by commas or line breaks. When it is empty or contains:

none

the agent reports no GPU metrics. When no file is configured, the agent reports every NVIDIA GPU visible to the process. After the file has loaded successfully, restart the agent to apply later changes. See Hardware metrics.

Agent flag reference

The complete current agent flag set is:

Flag	Environment variable	Default
`--engine`	—	`vllm`
`--backend-url`	—	`http://localhost:8888`
`--model`	—	Empty
`--health-url`	—	Empty
`--capacity`	—	`10`
`--version`	—	Build version; commonly `dev` locally
`--region`	—	`UE-France`
`--organization`	—	`Unknown`
`--machine`	—	`Unknown`
`--router-grpc`	—	`localhost:50051`
`--router-p2p`	—	`/ip4/127.0.0.1/tcp/9000`; deprecated no-op
`--tags`	—	`production`
`--http-timeout`	—	`120s`
`--stream-write-timeout`	—	`60s`
`--identity-path`	—	`./agent_identity.key`
`--p2p-listen-port`	—	`0`
`--hardware-sample-interval`	—	`2s`
`--engine-sample-interval`	—	`500ms`
`--routing-signal-interval`	—	`500ms`
`--jwt-secret-file`	`HIVENET_ROUTER_JWT_SECRET`	Required
`--gpu-devices-file`	—	Empty
`--gpu-model`	`HIVENET_ROUTER_GPU_MODEL`	Empty
`--deployment-id`	`HIVENET_ROUTER_DEPLOYMENT_ID`	Empty
`--replica-id`	`HIVENET_ROUTER_REPLICA_ID`	Empty
`--capability`	—	`llm`
`--hide-llm`	—	`false`
`--llm-pretty-name`	—	Empty
`--llm-info`	—	Empty

Logging configuration

Both processes use go-log.

Log level

export GOLOG_LOG_LEVEL=debug

Set one global level:

debug
info
warn
error

Or configure application subsystems individually:

export GOLOG_LOG_LEVEL="router=debug,policy=debug,api=info"

The application-defined subsystems are:

router
agent
api
auth
grpc
p2p
hardware
metrics
policy
storage

Dependencies such as libp2p may emit additional subsystem names.

JSON logs

For structured application logs:

export GOLOG_LOG_FMT=json

The agent adds its peer ID as a process-wide structured label. Audit records remain in their separate JSONL output. Logging environment variables are read at process startup.

Distributed tracing

Set an OTLP gRPC endpoint on the router, agents, or both:

export OTEL_EXPORTER_OTLP_ENDPOINT=tempo:4317

When the variable is empty or absent, tracing is disabled. The current exporter uses an insecure OTLP gRPC connection. Put the collector on a trusted network or use an appropriate protected intermediary. The processes identify themselves as:

hivenet-router
hivenet-agent

Changing the endpoint requires a process restart.

Environment parsing behavior

Router environment variables are loaded before CLI parsing. For typed router values such as integers and durations, an invalid environment value is generally ignored and the previous default remains active. For example:

export HIVENET_ROUTER_REQUEST_TIMEOUT="five minutes"

does not produce a valid duration and is ignored. The router therefore continues with:

60s

unless a CLI flag overrides it.

Invalid typed router environment values do not consistently stop startup.Read the router startup banner and verify the resolved configuration after every deployment change.

Invalid command-line values are more visible because Go’s flag parser normally exits with an error. Configuration values such as invalid auth modes, quota backends, policy files, and provider requirements fail during subsystem initialization.

Startup validation

Router validation

Router startup fails for conditions including:

missing JWT secret
JWT secret shorter than 32 bytes
session TTL of five minutes or less
max-tries-per-step below 1
negative queue depth
invalid libp2p announce address
invalid policy YAML
invalid per-model policy directory
unknown authentication mode
static API-key mode without keys
administrator API-key mode without administrator keys
unknown quota backend
provider fallback without the required provider key
storage initialization failure

Use positive values for:

queue-size
max-concurrent
p2p-max-conns-per-ip

even where the command entry point does not currently perform a dedicated validation check.

Agent validation

Agent startup or authentication fails for conditions including:

missing JWT secret
JWT secret shorter than 32 bytes
unknown engine
custom engine without a model
custom engine without a health URL
unknown capability
Ollama configured as a reranker
backend that never becomes ready
model discovery that never returns a model
non-positive capacity rejected by the router
JWT secret that does not match the router
unreachable router gRPC or libp2p interfaces

Reload or restart

Change	Apply with	Notes
Global policy file	`SIGHUP`	Invalid replacement leaves the current policy active
Per-model policy directory	`SIGHUP`	Directory is reread and replaced atomically
Static `auth.yaml` keys and quotas	`SIGHUP`	Current valid provider remains active after a failed reload
Administrator auth provider	`SIGHUP` or restart	Rebuilt from the running process environment
Dynamic client-key entries	Administration API	Changes take effect immediately
Dynamic client-auth mode	Restart	Cannot switch to or from dynamic mode through SIGHUP
Network addresses and ports	Restart	Listen sockets are created at startup
JWT secret	Coordinated router and agent restart	Changes gRPC identity and agent authentication
Provider API keys	Router restart	Provider adapters are built at startup
Quota backend	Router restart	Rate limiter is built at startup
Storage path or TTL	Router restart	Database is opened at startup
Audit-log path	Router restart	File is opened at process initialization
Logging or tracing environment	Process restart	Read during initialization
Agent metadata, backend, capacity, or sampling	Agent restart	Agent flags are parsed at startup

Editing a systemd EnvironmentFile, Docker .env file, or Kubernetes Secret does not modify the environment of an already running process. Recreate or restart the process when the changed value comes from its environment.

Send SIGHUP

Bare metal:

sudo kill -HUP \
  "$(pgrep hivenet-router)"

systemd:

sudo systemctl kill \
  --signal HUP \
  hivenet-router

Docker Compose:

docker compose kill \
  --signal SIGHUP \
  router

Inspect the router logs after reload. An invalid file leaves the previous valid configuration active, but the attempted change has not taken effect.

Router startup example

./bin/hivenet-router \
  --http-port 127.0.0.1:8080 \
  --grpc-port :50051 \
  --metrics-port 127.0.0.1:2112 \
  --p2p-port 9000 \
  --p2p-listen-addr 0.0.0.0 \
  --p2p-announce-addr \
    /dns4/router.example.com/tcp/9000 \
  --p2p-max-conns-per-ip 64 \
  --jwt-secret-file \
    /etc/hivenet-router/jwt.secret \
  --auth-config-file \
    /etc/hivenet-router/auth.yaml \
  --policy-model-dir \
    /etc/hivenet-router/policies \
  --disk-db-path \
    /var/lib/hivenet-router/badger \
  --request-timeout 5m

This example:

exposes gRPC and libp2p for remote agents
keeps the client API behind a local reverse proxy
keeps metrics on loopback
reads secrets and configuration from explicit paths
uses a policy directory
persists state outside the working directory

vLLM agent example

./bin/hivenet-agent \
  --engine vllm \
  --backend-url \
    http://127.0.0.1:8888 \
  --model \
    hivenet-router-code-model \
  --capability llm \
  --capacity 20 \
  --router-grpc \
    router.example.com:50051 \
  --jwt-secret-file \
    /etc/hivenet-router/jwt.secret \
  --identity-path \
    /var/lib/hivenet-router/agent-identity.key \
  --region EU-France \
  --organization "Acme Compute" \
  --machine gpu-worker-1 \
  --gpu-model "NVIDIA H100" \
  --tags production,realtime

The example does not set --router-p2p. The current agent receives the router’s dialable libp2p address during gRPC authentication.

Custom-engine example

./bin/hivenet-agent \
  --engine custom \
  --backend-url \
    http://127.0.0.1:1234 \
  --health-url \
    http://127.0.0.1:1234/health \
  --model \
    custom-chat-model \
  --capability llm \
  --router-grpc \
    router.example.com:50051 \
  --jwt-secret-file \
    /etc/hivenet-router/jwt.secret \
  --identity-path \
    /var/lib/hivenet-router/custom-agent-identity.key

A custom engine must implement the client-facing endpoint used by the request. Hivenet Router does not translate its API schema.

Generate a static client key

Run:

./bin/hivenet-router \
  keygen \
  --tenant acme-corp

The subcommand:

generates 32 random bytes
encodes a key beginning with sk-hivenet-
prints the raw key once
prints its SHA-256 hash
prints a masked preview
produces an auth.yaml entry

The tenant defaults to:

my-tenant

The value is limited to 200 characters. Store the raw key in a secret manager. Put only the generated hash in auth.yaml.

Next steps

auth.yaml reference

Configure static keys, administrator access, model restrictions, and quotas.

Policy YAML reference

Configure primary routing, fallback chains, provider fallback, and gates.

Detailed architecture

See where each configuration value affects the running system.

Error codes

Diagnose startup, authentication, routing, and backend failures.

Key rotation

Rotate client, administrator, agent, and provider credentials.

Prometheus metrics

Verify runtime behavior after configuration changes.

​View the installed options

​Configuration precedence

​Agent precedence

​Value formats

​Durations

​HTTP and gRPC listen addresses

​libp2p ports

​Paths

​Tags

​Router network settings

​HTTP API

​Metrics

​Remote agents

​Agents behind shared NAT

​Router routing and backpressure settings

​Built-in policy

​Policy-file precedence

​Global request queue

​Per-model wait queue

​Concurrent forwards

​Request deadline

​Router health and session settings

​Session lifetime

​Router storage settings

​Database reset

​Universal flush interval

​Router security and authentication settings

​Agent JWT secret

​Authentication file

​Router environment-only settings

​HIVENET_ROUTER_AUTH_MODE

​HIVENET_ROUTER_ADMIN_API_KEYS

​HIVENET_ROUTER_ALLOW_INSECURE_ADMIN

​HIVENET_ROUTER_MAX_REQUEST_BYTES

​Admission environment variables

​HIVENET_ROUTER_QUOTA_BACKEND

​Provider credentials

​Audit path

​Router flag reference

​Agent backend settings

​Supported engines

​Model discovery

​Capability

​Capacity

​Backend and router timeouts

​Stream write timeout

​Agent router and libp2p settings

​Router discovery

​Persistent identity

​Agent connection direction

​Agent metadata settings

​Region default

​Version

​GPU model

​Deployment ID

​Replica ID

​hide_llm metadata

​Agent telemetry settings

​Sampling and push intervals

​GPU-device file

​Agent flag reference

​Logging configuration

​Log level

​JSON logs

​Distributed tracing

​Environment parsing behavior

​Startup validation

​Router validation

​Agent validation

​Reload or restart

​Send SIGHUP

​Router startup example

​vLLM agent example

​Custom-engine example

​Generate a static client key

​Next steps

auth.yaml reference

Policy YAML reference

Detailed architecture

Error codes

View the installed options

Configuration precedence

Agent precedence

Value formats

Durations

HTTP and gRPC listen addresses

libp2p ports

Paths

Tags

Router network settings

HTTP API

Metrics

Remote agents

Agents behind shared NAT

Router routing and backpressure settings

Built-in policy

Policy-file precedence

Global request queue

Per-model wait queue

Concurrent forwards

Request deadline

Router health and session settings

Session lifetime

Router storage settings

Database reset

Universal flush interval

Router security and authentication settings

Agent JWT secret

Authentication file

Router environment-only settings

`HIVENET_ROUTER_AUTH_MODE`

`HIVENET_ROUTER_ADMIN_API_KEYS`

`HIVENET_ROUTER_ALLOW_INSECURE_ADMIN`

`HIVENET_ROUTER_MAX_REQUEST_BYTES`

Admission environment variables

`HIVENET_ROUTER_QUOTA_BACKEND`

Provider credentials

Audit path

Router flag reference

Agent backend settings

Supported engines

Model discovery

Capability

Capacity

Backend and router timeouts

Stream write timeout

Agent router and libp2p settings

Router discovery

Persistent identity

Agent connection direction

Agent metadata settings

Region default

Version

GPU model

Deployment ID

Replica ID

`hide_llm` metadata

Agent telemetry settings

Sampling and push intervals

GPU-device file

Agent flag reference

Logging configuration

Log level

JSON logs

Distributed tracing

Environment parsing behavior

Startup validation

Router validation

Agent validation

Reload or restart

Send SIGHUP

Router startup example

vLLM agent example

Custom-engine example

Generate a static client key

Next steps