HTTP/REST API Configuration

The HTTP gateway is configured with heliosdb-full startup flags and environment variables. The config file has no HTTP section (the server reads only [storage] keys from it). Run heliosdb-full --help to see every flag with its environment variable.

Port and bind address

Setting	Flag	Environment variable	Default
Port	--http-port <port>	HELIOSDB_HTTP_PORT	8443
Turn the gateway off	--no-http	—	on
Bind address (all listeners)	--bind-addr <addr>	HELIOSDB_BIND_ADDR	127.0.0.1
Allow a non-loopback bind	--allow-external	HELIOSDB_ALLOW_EXTERNAL	off

# Default: http://127.0.0.1:8443
heliosdb-full --data-dir /var/lib/heliosdb

# Another port, reachable from a private network
heliosdb-full --data-dir /var/lib/heliosdb --http-port 9443 \
  --bind-addr 10.0.0.12 --allow-external

--bind-addr applies to every listener. The server refuses to start on a non-loopback address without --allow-external (accepted values 1/0, true/false, yes/no, on/off).

In a container the image binds 0.0.0.0 and sets HELIOSDB_ALLOW_EXTERNAL=true; publish the port you use, for example -p 127.0.0.1:8443:8443, or -e HELIOSDB_HTTP_PORT=9443 -p 127.0.0.1:9443:9443.

TLS

TLS: next release

HeliosDB Full listeners do not terminate TLS; put a TLS-terminating proxy in front, and native PostgreSQL TLS (with post-quantum key exchange preferred) is planned for the next release. The --tls-cert, --tls-key and --tls-require flags in this section belong to that release.

The gateway serves plain HTTP; the TLS flags (--tls-cert, --tls-key, --tls-require) apply to the PostgreSQL listener only. For HTTPS, terminate TLS in front of the gateway:

server {
    listen 443 ssl;
    server_name db-api.example.internal;
    ssl_certificate     /etc/nginx/tls/db-api.crt;
    ssl_certificate_key /etc/nginx/tls/db-api.key;

    location / {
        proxy_pass http://127.0.0.1:8443;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Authentication

Setting	How	Default
API key	HELIOSDB_API_KEY environment variable	unset: every non-public route returns 401
Development without a key	--auth-mode trust (HELIOSDB_AUTH_MODE)	scram; trust is accepted on a loopback bind only

Clients send Authorization: Bearer <key> or X-API-Key: <key>. GET /, /health, /healthz, /ready, /readyz, /status and /api/v1/status need no key. The key is shared (not per user); treat it like a superuser password and load it from a secrets manager or a root-only environment file, never the command line.

Sessions, pool and limits

Setting	Flag (environment variable)	Default
Pinned sessions for transactions	--http-sessions	off (session routes return 501)
Handler pool for /api/v1/query	--http-pg-pool-size (HELIOSDB_HTTP_PG_POOL_SIZE)	16
New connections per client IP	--conn-rate-limit (HELIOSDB_CONN_RATE_LIMIT)	500 per minute
Queries per client IP	--query-rate-limit (HELIOSDB_QUERY_RATE_LIMIT)	not limited
Connection and query limiters	HELIOSDB_RATE_LIMITING=false turns them off	on
Concurrent connections, all listeners	--max-connections (HELIOSDB_MAX_CONNECTIONS)	10000

The session flags (--http-max-sessions, idle and lifetime timeouts, concurrency mode, IP binding, --node-id) and the AI provider variables are listed in the HTTP/REST API reference.

systemd example

# /etc/systemd/system/heliosdb.service (excerpt)
[Service]
EnvironmentFile=/etc/heliosdb/heliosdb.env   # HELIOSDB_API_KEY, HELIOSDB_SUPERUSER_PASSWORD; mode 0600
ExecStart=/usr/local/bin/heliosdb-full --data-dir /var/lib/heliosdb \
  --http-port 8443 --bind-addr 10.0.0.12 --allow-external